Generated API reference

@udid-tools/core

Classes

UdidToolsError

A sanitized, typed error. Secret input values are never included in its fields.

Extends

Error

Constructors

Constructor

new UdidToolsError(code, message, options?): UdidToolsError

Parameters

code

UdidToolsErrorCode

message

string

options?

UdidToolsErrorOptions = {}

Returns

UdidToolsError

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown

Inherited from

Error.cause

code

readonly code: UdidToolsErrorCode

details

readonly details: Readonly<Record<string, unknown>> | undefined

message

message: string

Inherited from

Error.message

name

name: string

Inherited from

Error.name

stack?

optional stack?: string

Inherited from

Error.stack

stackTraceLimit

static stackTraceLimit: number

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

Interfaces

CertificateInfo

Sanitized public metadata for an embedded CMS signer certificate.

Properties

issuer

readonly issuer: string

notAfter

readonly notAfter: Date

notBefore

readonly notBefore: Date

serialNumber

readonly serialNumber: string

sha256Fingerprint

readonly sha256Fingerprint: string

subject

readonly subject: string

EncodedBinaryInput

A textual binary container with an explicit, strict decoding rule.

Properties

encoding

readonly encoding: "base64" | "pem"

value

readonly value: string

GeneratedProfile

Generated XML or CMS profile bytes and format metadata.

Properties

contentType

readonly contentType: "application/x-apple-aspen-config"

data

readonly data: Uint8Array

profile

readonly profile: object

identifier

readonly identifier: string

kind

readonly kind: "profile-service"

uuid

readonly uuid: string

protection

readonly protection: object

encrypted

readonly encrypted: false

signed

readonly signed: boolean

ParseProfileServiceResponseOptions

Controls response acceptance, correlation, normalization, and resource limits.

Properties

allowUnsigned?

readonly optional allowUnsigned?: boolean

expectedAttributes?

readonly optional expectedAttributes?: readonly ("UDID" | "VERSION" | "PRODUCT" | "SERIAL" | "IMEI" | "MEID" | "ICCID" | "MAC_ADDRESS_EN0")[]

expectedChallenge?

readonly optional expectedChallenge?: ProfileServiceChallenge

limits?

readonly optional limits?: Partial<ResourceLimits>

requiredAttributes?

readonly optional requiredAttributes?: readonly ("UDID" | "VERSION" | "PRODUCT" | "SERIAL" | "IMEI" | "MEID" | "ICCID" | "MAC_ADDRESS_EN0")[]

verification?

readonly optional verification?: ResponseVerificationOptions

Pkcs12SigningIdentity

PKCS#12/PFX signing identity supported by the beta cryptographic profile.

Properties

data

readonly data: BinaryInput

passphrase?

readonly optional passphrase?: string

type

readonly type: "pkcs12"

PlistDictionary

A lossless property-list dictionary. Decoded dictionaries have a null prototype.

Indexable

[key: string]: PlistValue

ProfileGenerationOptions

Input to generateProfile.

Properties

limits?

readonly optional limits?: Partial<ResourceLimits>

profile

readonly profile: ProfileServiceDefinition

signing?

readonly optional signing?: SigningOptions

ProfileServiceAttributes

Known Apple response fields normalized to JavaScript naming.

Properties

iccid?

readonly optional iccid?: string

imei?

readonly optional imei?: string

macAddressEn0?

readonly optional macAddressEn0?: string

meid?

readonly optional meid?: string

product?

readonly optional product?: string

serialNumber?

readonly optional serialNumber?: string

udid?

readonly optional udid?: string

version?

readonly optional version?: string

ProfileServiceDefinition

Complete typed definition of Apple’s special Profile Service profile.

Properties

description?

readonly optional description?: string

displayName

readonly displayName: string

extensions?

readonly optional extensions?: Readonly<Record<string, PlistValue>>

Additional top-level fields retained for forwards compatibility.

identifier

readonly identifier: string

kind

readonly kind: "profile-service"

organization?

readonly optional organization?: string

service

readonly service: object

challenge?

readonly optional challenge?: ProfileServiceChallenge

deviceAttributes

readonly deviceAttributes: readonly DeviceAttribute[]

extensions?

readonly optional extensions?: Readonly<Record<string, PlistValue>>

responseUrl

readonly responseUrl: string

uuid?

readonly optional uuid?: string

ProfileServiceResponse

Verified and decoded Apple Profile Service device response.

Properties

attributes

readonly attributes: ProfileServiceAttributes

challenge?

readonly optional challenge?: string | Uint8Array<ArrayBufferLike>

raw

readonly raw: Readonly<Record<string, PlistValue>>

signature

readonly signature: object

present

readonly present: boolean

signers

readonly signers: readonly CertificateInfo[]

trusted

readonly trusted: boolean | null

valid

readonly valid: boolean | null

ResourceLimits

Bounded-work policy applied before and during parsing, encoding, and crypto.

Properties

maxArrayItems

readonly maxArrayItems: number

maxAsn1Depth

readonly maxAsn1Depth: number

maxAsn1Nodes

readonly maxAsn1Nodes: number

maxCertificateBytes

readonly maxCertificateBytes: number

maxCertificates

readonly maxCertificates: number

maxDictionaryKeys

readonly maxDictionaryKeys: number

maxInputBytes

readonly maxInputBytes: number

maxOutputBytes

readonly maxOutputBytes: number

maxPlistDepth

readonly maxPlistDepth: number

maxStringBytes

readonly maxStringBytes: number

SigningOptions

Optional signing configuration. Its presence requests signed output.

Properties

certificateChain?

readonly optional certificateChain?: readonly BinaryInput[]

digestAlgorithm?

readonly optional digestAlgorithm?: "sha256"

identity

readonly identity: Pkcs12SigningIdentity

UdidToolsErrorOptions

Properties

details?

readonly optional details?: Readonly<Record<string, unknown>>

UdidToolsWarning

Properties

code

readonly code: UdidToolsWarningCode

details?

readonly optional details?: Readonly<Record<string, unknown>>

message

readonly message: string

Type Aliases

BinaryInput

BinaryInput = EncodedBinaryInput | Uint8Array

Binary bytes or their explicit base64/PEM representation.

CertificateInput

CertificateInput = BinaryInput

X.509 certificate input in DER bytes, canonical base64, or PEM.

CustomDeviceAttribute

CustomDeviceAttribute = string & object

Deliberately opted-in, forward-compatible uppercase device attribute.

Type Declaration

[customDeviceAttributeBrand]

readonly [customDeviceAttributeBrand]: true

DeviceAttribute

DeviceAttribute = CustomDeviceAttribute | KnownDeviceAttribute

A known or explicitly branded custom Profile Service attribute name.

KnownDeviceAttribute

KnownDeviceAttribute = typeof KNOWN_DEVICE_ATTRIBUTES[number]

A device attribute currently normalized by the public response API.

PlistPrimitive

PlistPrimitive = boolean | Date | number | string | Uint8Array

Scalar values supported by the XML property-list codec.

PlistValue

PlistValue = PlistPrimitive | readonly PlistValue[] | PlistDictionary

Any value representable by the library’s bounded XML property-list codec.

ProfileServiceChallenge

ProfileServiceChallenge = { type: "data"; value: Uint8Array; } | { type: "string"; value: string; }

Opaque correlation value included in the request profile and device response.

ProfileServiceResponseInput

ProfileServiceResponseInput = ArrayBuffer | string | Uint8Array

Raw CMS/XML input accepted by the response parser.

ResourceLimitsInput

ResourceLimitsInput = Partial<ResourceLimits>

Per-call resource-limit overrides.

ResponseVerificationOptions

ResponseVerificationOptions = { mode: "none"; } | { mode: "signature"; } | { intermediates?: readonly CertificateInput[]; mode: "trust-chain"; trustAnchors: readonly CertificateInput[]; }

Explicit response verification policy; no system trust is used.

Result

Result<T> = { ok: true; value: T; warnings: readonly UdidToolsWarning[]; } | { error: UdidToolsError; ok: false; }

Non-throwing operation result. Successful values may include actionable, non-fatal warnings; failures contain one sanitized typed error.

Type Parameters

T

T

UdidToolsErrorCode

UdidToolsErrorCode = "CERTIFICATE_KEY_MISMATCH" | "CHALLENGE_MISMATCH" | "INCORRECT_PASSPHRASE" | "INPUT_TOO_LARGE" | "INTERNAL_ERROR" | "INVALID_CERTIFICATE" | "INVALID_CONFIGURATION" | "INVALID_PKCS12" | "INVALID_PRIVATE_KEY" | "INVALID_PROFILE_IDENTIFIER" | "INVALID_RESPONSE_URL" | "INVALID_SIGNATURE" | "MALFORMED_CMS" | "MALFORMED_PLIST" | "MISSING_CHALLENGE" | "MISSING_REQUIRED_ATTRIBUTE" | "MISSING_SIGNING_MATERIAL" | "OUTPUT_TOO_LARGE" | "PROFILE_SIGNING_FAILED" | "UNSUPPORTED_ALGORITHM" | "UNTRUSTED_SIGNER"

Stable machine-readable error codes returned by the public API.

UdidToolsWarningCode

UdidToolsWarningCode = "CERTIFICATE_EXPIRES_SOON" | "CERTIFICATE_NOT_YET_VALID" | "DUPLICATE_CERTIFICATE_IGNORED" | "INSECURE_RESPONSE_URL" | "OPTIONAL_ATTRIBUTE_MISSING" | "SIGNER_TRUST_NOT_CHECKED" | "UNKNOWN_RESPONSE_ATTRIBUTE"