@structured-id/ids 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { MessageType } from '@protobuf-ts/runtime';
+
+/** The identifier kinds this package delivers: one per `sid.v1.ids` message. */
+type IdKind = "BindingId" | "MachineUserId" | "PasswordOperationId" | "ProvisioningConnectorId" | "ProvisioningCredentialId" | "ResourceId";
+/** Why a value is not a valid identifier. */
+type IdErrorReason = 
+/** The text is not a UUID in any accepted textual form. */
+{
+    readonly type: "malformed";
+}
+/** Binary form of a length other than 16 bytes. */
+ | {
+    readonly type: "length";
+    readonly length: number;
+}
+/** The nil UUID (all zero bits). */
+ | {
+    readonly type: "nil";
+}
+/** The max UUID (all one bits). */
+ | {
+    readonly type: "max";
+}
+/** The variant bits are not those of RFC 9562. */
+ | {
+    readonly type: "variant";
+}
+/** An RFC 9562 UUID of a version other than 7. */
+ | {
+    readonly type: "version";
+    readonly version: number;
+};
+/**
+ * A value that is not a valid identifier of the requested kind. Carries the
+ * kind and the reason, never the value, so it can be logged freely.
+ */
+declare class IdError extends Error {
+    readonly kind: IdKind;
+    readonly reason: IdErrorReason;
+    readonly name = "IdError";
+    constructor(kind: IdKind, reason: IdErrorReason);
+}
+/** A required identifier message was absent. Absence is never a default. */
+declare class MissingIdError extends Error {
+    readonly kind: IdKind;
+    readonly name = "MissingIdError";
+    constructor(kind: IdKind);
+}
+
+declare class BindingId$Type extends MessageType<BindingId$1> {
+    constructor();
+}
+/**
+ * A Profile's identity at one organization: the pairwise subject that
+ * organization's services see. Opaque and unlinkable across organizations;
+ * it never carries or reveals a ProfileId.
+ *
+ * @generated from protobuf message sid.v1.ids.BindingId
+ */
+interface BindingId$1 {
+    /**
+     * Exactly 16 bytes: an RFC 9562 UUID of version 7 and the RFC 9562 variant,
+     * in network byte order. Nil, max, other lengths, versions and variants are
+     * invalid. Issued by SID; compared by exact byte equality.
+     *
+     * @generated from protobuf field: bytes value = 1
+     */
+    value: Uint8Array;
+}
+/**
+ * @generated MessageType for protobuf message sid.v1.ids.BindingId
+ */
+declare const BindingId$1: BindingId$Type;
+declare class PasswordOperationId$Type extends MessageType<PasswordOperationId$1> {
+    constructor();
+}
+/**
+ * One password-installing operation (a registration, change or authorized
+ * reset) from its preparation to its commit. Every step and retry of the
+ * operation carries it, so a lost response resolves to the operation's one
+ * outcome instead of starting another.
+ *
+ * @generated from protobuf message sid.v1.ids.PasswordOperationId
+ */
+interface PasswordOperationId$1 {
+    /**
+     * Exactly 16 bytes: an RFC 9562 UUID of version 7 and the RFC 9562 variant,
+     * in network byte order. Nil, max, other lengths, versions and variants are
+     * invalid. Issued by SID; compared by exact byte equality.
+     *
+     * @generated from protobuf field: bytes value = 1
+     */
+    value: Uint8Array;
+}
+/**
+ * @generated MessageType for protobuf message sid.v1.ids.PasswordOperationId
+ */
+declare const PasswordOperationId$1: PasswordOperationId$Type;
+declare class MachineUserId$Type extends MessageType<MachineUserId$1> {
+    constructor();
+}
+/**
+ * A non-human actor (a service, bot or agent) with its own SID credentials.
+ * Not a Binding, a Profile or a device, whatever its bytes.
+ *
+ * @generated from protobuf message sid.v1.ids.MachineUserId
+ */
+interface MachineUserId$1 {
+    /**
+     * Exactly 16 bytes: an RFC 9562 UUID of version 7 and the RFC 9562 variant,
+     * in network byte order. Nil, max, other lengths, versions and variants are
+     * invalid. Issued by SID; compared by exact byte equality.
+     *
+     * @generated from protobuf field: bytes value = 1
+     */
+    value: Uint8Array;
+}
+/**
+ * @generated MessageType for protobuf message sid.v1.ids.MachineUserId
+ */
+declare const MachineUserId$1: MachineUserId$Type;
+declare class ProvisioningConnectorId$Type extends MessageType<ProvisioningConnectorId$1> {
+    constructor();
+}
+/**
+ * A provisioning connector: one directory source sending SCIM to an
+ * organization, or one target the organization provisions, acting as its own
+ * actor with its own credentials and grants. Not a machine user or a Profile.
+ *
+ * @generated from protobuf message sid.v1.ids.ProvisioningConnectorId
+ */
+interface ProvisioningConnectorId$1 {
+    /**
+     * Exactly 16 bytes: an RFC 9562 UUID of version 7 and the RFC 9562 variant,
+     * in network byte order. Nil, max, other lengths, versions and variants are
+     * invalid. Issued by SID; compared by exact byte equality.
+     *
+     * @generated from protobuf field: bytes value = 1
+     */
+    value: Uint8Array;
+}
+/**
+ * @generated MessageType for protobuf message sid.v1.ids.ProvisioningConnectorId
+ */
+declare const ProvisioningConnectorId$1: ProvisioningConnectorId$Type;
+declare class ResourceId$Type extends MessageType<ResourceId$1> {
+    constructor();
+}
+/**
+ * A registered protected resource: the application or API at which access is
+ * enforced, in its issuer's context. Not an OAuth client and not an audience
+ * string; its indicator and issuer come from its registration.
+ *
+ * @generated from protobuf message sid.v1.ids.ResourceId
+ */
+interface ResourceId$1 {
+    /**
+     * Exactly 16 bytes: an RFC 9562 UUID of version 7 and the RFC 9562 variant,
+     * in network byte order. Nil, max, other lengths, versions and variants are
+     * invalid. Issued by SID; compared by exact byte equality.
+     *
+     * @generated from protobuf field: bytes value = 1
+     */
+    value: Uint8Array;
+}
+/**
+ * @generated MessageType for protobuf message sid.v1.ids.ResourceId
+ */
+declare const ResourceId$1: ResourceId$Type;
+declare class ProvisioningCredentialId$Type extends MessageType<ProvisioningCredentialId$1> {
+    constructor();
+}
+/**
+ * One credential of a provisioning connector: the reference listings,
+ * rotations, revocations and audit records name. Never the secret itself.
+ *
+ * @generated from protobuf message sid.v1.ids.ProvisioningCredentialId
+ */
+interface ProvisioningCredentialId$1 {
+    /**
+     * Exactly 16 bytes: an RFC 9562 UUID of version 7 and the RFC 9562 variant,
+     * in network byte order. Nil, max, other lengths, versions and variants are
+     * invalid. Issued by SID; compared by exact byte equality.
+     *
+     * @generated from protobuf field: bytes value = 1
+     */
+    value: Uint8Array;
+}
+/**
+ * @generated MessageType for protobuf message sid.v1.ids.ProvisioningCredentialId
+ */
+declare const ProvisioningCredentialId$1: ProvisioningCredentialId$Type;
+
+declare namespace ids {
+  export { BindingId$1 as BindingId, MachineUserId$1 as MachineUserId, PasswordOperationId$1 as PasswordOperationId, ProvisioningConnectorId$1 as ProvisioningConnectorId, ProvisioningCredentialId$1 as ProvisioningCredentialId, ResourceId$1 as ResourceId };
+}
+
+/**
+ * The common behaviour of every identifier. A value is always a valid UUIDv7:
+ * it is built only through validation and its bytes are private. Each kind is
+ * its own class with a literal `kind`, so values of different kinds are
+ * different types even when their bytes are equal.
+ *
+ * A valid identifier proves only its shape. It does not prove that the entity
+ * exists, whom it belongs to, or that the caller may act on it.
+ */
+declare abstract class Identifier {
+    #private;
+    abstract readonly kind: IdKind;
+    protected constructor(bytes: Uint8Array);
+    /** A copy of the 16 bytes in network order: the wire value. */
+    toBytes(): Uint8Array;
+    /** Lowercase hyphenated text, for display only; the wire carries bytes. */
+    toString(): string;
+    /** The same text as `toString`, so JSON logs show a readable value. */
+    toJSON(): string;
+    /** True for an identifier of the same kind with the same bytes. */
+    equals(other: unknown): boolean;
+}
+/**
+ * A Profile's identity at one organization: the pairwise subject that
+ * organization's services see. Opaque and unlinkable across organizations.
+ */
+declare class BindingId extends Identifier {
+    static readonly kind = "BindingId";
+    readonly kind = "BindingId";
+    private constructor();
+    /** Accept 16 bytes as this identifier, or throw `IdError` saying why not. */
+    static fromBytes(bytes: Uint8Array): BindingId;
+    /** Accept a textual UUID as this identifier, or throw `IdError`. */
+    static parse(text: string): BindingId;
+    /** Validate a decoded wire message; throws `IdError`. */
+    static fromWire(message: BindingId$1): BindingId;
+    /** The wire message carrying this identifier's bytes. */
+    toWire(): BindingId$1;
+}
+/**
+ * A non-human actor (a service, bot or agent) with its own credentials. Not a
+ * Binding, a Profile or a device, whatever its bytes.
+ */
+declare class MachineUserId extends Identifier {
+    static readonly kind = "MachineUserId";
+    readonly kind = "MachineUserId";
+    private constructor();
+    /** Accept 16 bytes as this identifier, or throw `IdError` saying why not. */
+    static fromBytes(bytes: Uint8Array): MachineUserId;
+    /** Accept a textual UUID as this identifier, or throw `IdError`. */
+    static parse(text: string): MachineUserId;
+    /** Validate a decoded wire message; throws `IdError`. */
+    static fromWire(message: MachineUserId$1): MachineUserId;
+    /** The wire message carrying this identifier's bytes. */
+    toWire(): MachineUserId$1;
+}
+/**
+ * One password-installing operation (a registration, change or authorized
+ * reset) from its preparation to its commit. Every retry carries it, so a lost
+ * response resolves to the operation's one outcome.
+ */
+declare class PasswordOperationId extends Identifier {
+    static readonly kind = "PasswordOperationId";
+    readonly kind = "PasswordOperationId";
+    private constructor();
+    /** Accept 16 bytes as this identifier, or throw `IdError` saying why not. */
+    static fromBytes(bytes: Uint8Array): PasswordOperationId;
+    /** Accept a textual UUID as this identifier, or throw `IdError`. */
+    static parse(text: string): PasswordOperationId;
+    /** Validate a decoded wire message; throws `IdError`. */
+    static fromWire(message: PasswordOperationId$1): PasswordOperationId;
+    /** The wire message carrying this identifier's bytes. */
+    toWire(): PasswordOperationId$1;
+}
+/**
+ * A provisioning connector: one directory source or target acting as its own
+ * actor with its own credentials and grants. Not a machine user or a Profile.
+ */
+declare class ProvisioningConnectorId extends Identifier {
+    static readonly kind = "ProvisioningConnectorId";
+    readonly kind = "ProvisioningConnectorId";
+    private constructor();
+    /** Accept 16 bytes as this identifier, or throw `IdError` saying why not. */
+    static fromBytes(bytes: Uint8Array): ProvisioningConnectorId;
+    /** Accept a textual UUID as this identifier, or throw `IdError`. */
+    static parse(text: string): ProvisioningConnectorId;
+    /** Validate a decoded wire message; throws `IdError`. */
+    static fromWire(message: ProvisioningConnectorId$1): ProvisioningConnectorId;
+    /** The wire message carrying this identifier's bytes. */
+    toWire(): ProvisioningConnectorId$1;
+}
+/**
+ * One credential of a provisioning connector: the reference listings,
+ * rotations, revocations and audit records name. Never the secret itself.
+ */
+declare class ProvisioningCredentialId extends Identifier {
+    static readonly kind = "ProvisioningCredentialId";
+    readonly kind = "ProvisioningCredentialId";
+    private constructor();
+    /** Accept 16 bytes as this identifier, or throw `IdError` saying why not. */
+    static fromBytes(bytes: Uint8Array): ProvisioningCredentialId;
+    /** Accept a textual UUID as this identifier, or throw `IdError`. */
+    static parse(text: string): ProvisioningCredentialId;
+    /** Validate a decoded wire message; throws `IdError`. */
+    static fromWire(message: ProvisioningCredentialId$1): ProvisioningCredentialId;
+    /** The wire message carrying this identifier's bytes. */
+    toWire(): ProvisioningCredentialId$1;
+}
+/**
+ * A registered protected resource: the application or API at which access is
+ * enforced, in its issuer's context. Not an OAuth client or an audience string.
+ */
+declare class ResourceId extends Identifier {
+    static readonly kind = "ResourceId";
+    readonly kind = "ResourceId";
+    private constructor();
+    /** Accept 16 bytes as this identifier, or throw `IdError` saying why not. */
+    static fromBytes(bytes: Uint8Array): ResourceId;
+    /** Accept a textual UUID as this identifier, or throw `IdError`. */
+    static parse(text: string): ResourceId;
+    /** Validate a decoded wire message; throws `IdError`. */
+    static fromWire(message: ResourceId$1): ResourceId;
+    /** The wire message carrying this identifier's bytes. */
+    toWire(): ResourceId$1;
+}
+/** An identifier class: its kind and its checked wire conversion. */
+interface IdType<T, W> {
+    readonly kind: IdKind;
+    fromWire(message: W): T;
+}
+/**
+ * The identifier in a required message field: absence throws
+ * `MissingIdError`, an invalid value throws `IdError`.
+ */
+declare function required<T, W>(type: IdType<T, W>, message: W | undefined): T;
+/**
+ * The identifier in an optional message field: absence stays `undefined`, a
+ * present but invalid value throws `IdError` (an empty message is invalid,
+ * not absent).
+ */
+declare function optional<T, W>(type: IdType<T, W>, message: W | undefined): T | undefined;
+
+/**
+ * StructuredID identifiers for TypeScript.
+ *
+ * Each identifier kind is its own class (`BindingId`, `MachineUserId`, ...),
+ * built only through validation: exactly 16 bytes of an RFC 9562 UUIDv7, not
+ * nil or max. `wire` holds the generated `sid.v1.ids` messages with their
+ * binary and standard ProtoJSON codecs; decoding one proves nothing, and the
+ * checked conversion (`fromWire`, `required`, `optional`) validates it.
+ */
+
+/** The include-relative path of the identifier schema this package carries. */
+declare const PROTO_PATH = "sid/v1/ids/ids.proto";
+
+export { BindingId, IdError, type IdErrorReason, type IdKind, type IdType, MachineUserId, MissingIdError, PROTO_PATH, PasswordOperationId, ProvisioningConnectorId, ProvisioningCredentialId, ResourceId, optional, required, ids as wire };