@oxy.so/contracts 1.0.0

package/dist/types/sessionStatus.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Canonical contract for `GET /auth/session/status/:sessionToken`.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the cross-app device-flow
+ * session-status payload and the sanitized public application identity it
+ * embeds. The API validates its OUTPUT against these schemas; the auth app
+ * (consent UI) validates its INPUT against the same schemas. Because there is
+ * exactly one definition, the producer and the consumer cannot drift.
+ *
+ * The class of bug that motivated moving this into `@oxy.so/contracts`: the auth
+ * app's LOCAL `sessionStatusSchema` typed `sessionId` as a non-nullable
+ * `z.string().optional()`. The producer emits `sessionId: authorizedSessionId ||
+ * null`, so a PENDING session (not yet authorized) carries `sessionId: null` —
+ * `.optional()` permits `undefined`/missing but REJECTS `null`, so `safeParse`
+ * failed, the whole response collapsed to `null`, and the consent screen showed
+ * "Unable to identify the requesting application". Pinning the nullability in one
+ * shared place makes that drift impossible.
+ *
+ * Faithful to the producers:
+ *  - `packages/api/src/utils/serializeApplication.ts` `serializePublicApplication`
+ *    — the ONLY shape returned to an unauthenticated consent UI. Optional fields
+ *    (`description`, `icon`, `websiteUrl`, `privacyPolicyUrl`, `termsUrl`,
+ *    `developerName`) are OMITTED when absent (never serialized as `null`), so
+ *    they are `.optional()` — NOT `.nullable()`. `type` is the `Application.type`
+ *    enum.
+ *  - `packages/api/src/routes/auth.ts` `GET /session/status/:sessionToken` — the
+ *    inner object of the API's `{ data: ... }` success envelope. The handler
+ *    ALWAYS emits `status`, `authorized` (`status === 'authorized'`),
+ *    `sessionToken`, `expiresAt` (ISO string), and `application` (resolved object
+ *    OR `null`). It ALWAYS emits `sessionId` / `publicKey` / `userId`, each as a
+ *    string value OR `null` (`authorizedSessionId || null`, `authorizedBy ||
+ *    null`, `authorizedUserId?.toString() || null`).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Application `type` enum. Mirrors `APPLICATION_TYPES` in
+ * `packages/api/src/models/Application.ts` (`first_party` | `third_party` |
+ * `internal` | `system`).
+ */
+export declare const applicationTypeSchema: z.ZodEnum<["first_party", "third_party", "internal", "system"]>;
+export type ApplicationTypeContract = z.infer<typeof applicationTypeSchema>;
+/**
+ * The display-safe public identity of a requesting application, exactly as
+ * `serializePublicApplication` emits it. Returned by the API inside
+ * `GET /auth/session/status/:sessionToken` (device flow) and
+ * `GET /auth/oauth/client/:clientId` (OAuth code flow).
+ *
+ * Optional fields are `.optional()` (NOT `.nullable()`): the serializer OMITS
+ * `description` / `icon` / `websiteUrl` / `privacyPolicyUrl` / `termsUrl` /
+ * `developerName` when the underlying value is absent — it never writes `null`
+ * for them. `developerName` is only attached for non-official apps when a name
+ * could be resolved.
+ */
+export declare const publicApplicationSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    websiteUrl: z.ZodOptional<z.ZodString>;
+    privacyPolicyUrl: z.ZodOptional<z.ZodString>;
+    termsUrl: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<["first_party", "third_party", "internal", "system"]>;
+    isOfficial: z.ZodBoolean;
+    isInternal: z.ZodBoolean;
+    scopes: z.ZodArray<z.ZodString, "many">;
+    developerName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "internal" | "system" | "first_party" | "third_party";
+    name: string;
+    id: string;
+    isOfficial: boolean;
+    isInternal: boolean;
+    scopes: string[];
+    description?: string | undefined;
+    icon?: string | undefined;
+    websiteUrl?: string | undefined;
+    privacyPolicyUrl?: string | undefined;
+    termsUrl?: string | undefined;
+    developerName?: string | undefined;
+}, {
+    type: "internal" | "system" | "first_party" | "third_party";
+    name: string;
+    id: string;
+    isOfficial: boolean;
+    isInternal: boolean;
+    scopes: string[];
+    description?: string | undefined;
+    icon?: string | undefined;
+    websiteUrl?: string | undefined;
+    privacyPolicyUrl?: string | undefined;
+    termsUrl?: string | undefined;
+    developerName?: string | undefined;
+}>;
+export type PublicApplicationResponse = z.infer<typeof publicApplicationSchema>;
+/**
+ * The inner object of `GET /auth/session/status/:sessionToken` (inside the API's
+ * `{ data: ... }` envelope).
+ *
+ * `application` is the resolved {@link publicApplicationSchema} identity of the
+ * requesting application, or `null` when the bound app was hard-deleted / is no
+ * longer `active` (defensive — normally always present).
+ *
+ * `sessionId` / `publicKey` / `userId` are `.nullable().optional()`: the producer
+ * ALWAYS emits the key, with a string for an AUTHORIZED session or `null` for a
+ * PENDING one. `.nullable()` accepts the PENDING `null`; `.optional()` is belt-
+ * and-braces so a consumer is never broken by a future projection that drops the
+ * key. (`.optional()` alone would REJECT the PENDING `null` — that was the bug.)
+ *
+ * `authorized` / `sessionToken` / `expiresAt` are emitted unconditionally by the
+ * current producer and are never `null`, but stay `.optional()` so the contract
+ * tolerates leaner shapes from other producers of this same payload without a
+ * coordinated bump.
+ *
+ * `pushSentAt` / `openedAt` are DELIVERY PROGRESS, not authorization state: they
+ * let a waiting surface render "Check Commons on your phone" → "Opened in
+ * Commons" without inventing competing statuses. `status` remains the only
+ * authority on whether the request is pending, authorized, cancelled or expired.
+ * Both are `.nullable().optional()` for the same reason as `sessionId` — the
+ * producer always emits the key with `null` until that step happens, and an
+ * older API that omits them entirely must degrade, not fail the parse.
+ */
+export declare const sessionStatusSchema: z.ZodObject<{
+    status: z.ZodString;
+    authorized: z.ZodOptional<z.ZodBoolean>;
+    sessionToken: z.ZodOptional<z.ZodString>;
+    application: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        websiteUrl: z.ZodOptional<z.ZodString>;
+        privacyPolicyUrl: z.ZodOptional<z.ZodString>;
+        termsUrl: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<["first_party", "third_party", "internal", "system"]>;
+        isOfficial: z.ZodBoolean;
+        isInternal: z.ZodBoolean;
+        scopes: z.ZodArray<z.ZodString, "many">;
+        developerName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "internal" | "system" | "first_party" | "third_party";
+        name: string;
+        id: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        privacyPolicyUrl?: string | undefined;
+        termsUrl?: string | undefined;
+        developerName?: string | undefined;
+    }, {
+        type: "internal" | "system" | "first_party" | "third_party";
+        name: string;
+        id: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        privacyPolicyUrl?: string | undefined;
+        termsUrl?: string | undefined;
+        developerName?: string | undefined;
+    }>>>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    publicKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /**
+     * What approving this request does. Legacy rows read as `device_sign_in`.
+     * OAuth-bound sessions finalize into an authorization code (no `sessionId`).
+     */
+    purpose: z.ZodOptional<z.ZodEnum<["device_sign_in", "oauth_authorization"]>>;
+    pushSentAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    openedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    expiresAt?: string | undefined;
+    sessionId?: string | null | undefined;
+    userId?: string | null | undefined;
+    publicKey?: string | null | undefined;
+    sessionToken?: string | undefined;
+    authorized?: boolean | undefined;
+    application?: {
+        type: "internal" | "system" | "first_party" | "third_party";
+        name: string;
+        id: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        privacyPolicyUrl?: string | undefined;
+        termsUrl?: string | undefined;
+        developerName?: string | undefined;
+    } | null | undefined;
+    purpose?: "device_sign_in" | "oauth_authorization" | undefined;
+    pushSentAt?: string | null | undefined;
+    openedAt?: string | null | undefined;
+}, {
+    status: string;
+    expiresAt?: string | undefined;
+    sessionId?: string | null | undefined;
+    userId?: string | null | undefined;
+    publicKey?: string | null | undefined;
+    sessionToken?: string | undefined;
+    authorized?: boolean | undefined;
+    application?: {
+        type: "internal" | "system" | "first_party" | "third_party";
+        name: string;
+        id: string;
+        isOfficial: boolean;
+        isInternal: boolean;
+        scopes: string[];
+        description?: string | undefined;
+        icon?: string | undefined;
+        websiteUrl?: string | undefined;
+        privacyPolicyUrl?: string | undefined;
+        termsUrl?: string | undefined;
+        developerName?: string | undefined;
+    } | null | undefined;
+    purpose?: "device_sign_in" | "oauth_authorization" | undefined;
+    pushSentAt?: string | null | undefined;
+    openedAt?: string | null | undefined;
+}>;
+export type SessionStatusResponse = z.infer<typeof sessionStatusSchema>;

package/dist/types/transparency.d.ts

@@ -0,0 +1,392 @@
+import { z } from 'zod';
+/**
+ * One signer's endorsement of a checkpoint's signed fields.
+ *
+ * The operator and every independent witness produce this same shape over the
+ * SAME bytes, so the array on a checkpoint can grow without coordination.
+ */
+export declare const transparencyCheckpointSignatureSchema: z.ZodObject<{
+    /** Uncompressed hex public key of the signer. */
+    publicKey: z.ZodString;
+    alg: z.ZodLiteral<"ES256K-DER-SHA256">;
+    /** DER-encoded hex secp256k1 signature over the checkpoint signing input. */
+    signature: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    publicKey: string;
+    alg: "ES256K-DER-SHA256";
+}, {
+    signature: string;
+    publicKey: string;
+    alg: "ES256K-DER-SHA256";
+}>;
+/** Where a checkpoint root was published on a public chain. */
+export declare const transparencyAnchorSchema: z.ZodObject<{
+    /** Chain/network identifier, e.g. `faircoin-main`. */
+    network: z.ZodString;
+    txid: z.ZodString;
+    confirmations: z.ZodNumber;
+    /** When the anchoring transaction was broadcast (ms epoch). */
+    anchoredAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    network: string;
+    txid: string;
+    confirmations: number;
+    anchoredAt: number;
+}, {
+    network: string;
+    txid: string;
+    confirmations: number;
+    anchoredAt: number;
+}>;
+/**
+ * A published checkpoint.
+ *
+ * `signatures` is non-empty by contract: an unsigned root commits nobody and
+ * must never be served as a checkpoint. `anchors` may be empty — a checkpoint is
+ * published immediately and anchored asynchronously, so "not yet anchored" is a
+ * normal, temporary state rather than an error.
+ */
+export declare const transparencyCheckpointSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    /** End of the committed period (ms epoch). */
+    periodEnd: z.ZodNumber;
+    /** Number of subjects (leaves) committed. */
+    treeSize: z.ZodNumber;
+    root: z.ZodString;
+    /** Hash of the previous checkpoint; `null` only at genesis. */
+    prevCheckpointHash: z.ZodNullable<z.ZodString>;
+    signatures: z.ZodArray<z.ZodObject<{
+        /** Uncompressed hex public key of the signer. */
+        publicKey: z.ZodString;
+        alg: z.ZodLiteral<"ES256K-DER-SHA256">;
+        /** DER-encoded hex secp256k1 signature over the checkpoint signing input. */
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        publicKey: string;
+        alg: "ES256K-DER-SHA256";
+    }, {
+        signature: string;
+        publicKey: string;
+        alg: "ES256K-DER-SHA256";
+    }>, "many">;
+    anchors: z.ZodArray<z.ZodObject<{
+        /** Chain/network identifier, e.g. `faircoin-main`. */
+        network: z.ZodString;
+        txid: z.ZodString;
+        confirmations: z.ZodNumber;
+        /** When the anchoring transaction was broadcast (ms epoch). */
+        anchoredAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        network: string;
+        txid: string;
+        confirmations: number;
+        anchoredAt: number;
+    }, {
+        network: string;
+        txid: string;
+        confirmations: number;
+        anchoredAt: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    index: number;
+    periodEnd: number;
+    treeSize: number;
+    root: string;
+    prevCheckpointHash: string | null;
+    signatures: {
+        signature: string;
+        publicKey: string;
+        alg: "ES256K-DER-SHA256";
+    }[];
+    anchors: {
+        network: string;
+        txid: string;
+        confirmations: number;
+        anchoredAt: number;
+    }[];
+}, {
+    index: number;
+    periodEnd: number;
+    treeSize: number;
+    root: string;
+    prevCheckpointHash: string | null;
+    signatures: {
+        signature: string;
+        publicKey: string;
+        alg: "ES256K-DER-SHA256";
+    }[];
+    anchors: {
+        network: string;
+        txid: string;
+        confirmations: number;
+        anchoredAt: number;
+    }[];
+}>;
+/**
+ * An inclusion proof for one subject against one checkpoint.
+ *
+ * Carries the leaf PREIMAGE (`subjectDid`, `seq`, `headRecordId`) as well as the
+ * `leaf` digest so the verifier re-derives the leaf itself rather than trusting
+ * the server's hash, then walks `proof` up to the checkpoint's `root`.
+ */
+export declare const transparencyInclusionProofSchema: z.ZodObject<{
+    checkpoint: z.ZodObject<{
+        index: z.ZodNumber;
+        /** End of the committed period (ms epoch). */
+        periodEnd: z.ZodNumber;
+        /** Number of subjects (leaves) committed. */
+        treeSize: z.ZodNumber;
+        root: z.ZodString;
+        /** Hash of the previous checkpoint; `null` only at genesis. */
+        prevCheckpointHash: z.ZodNullable<z.ZodString>;
+        signatures: z.ZodArray<z.ZodObject<{
+            /** Uncompressed hex public key of the signer. */
+            publicKey: z.ZodString;
+            alg: z.ZodLiteral<"ES256K-DER-SHA256">;
+            /** DER-encoded hex secp256k1 signature over the checkpoint signing input. */
+            signature: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }, {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }>, "many">;
+        anchors: z.ZodArray<z.ZodObject<{
+            /** Chain/network identifier, e.g. `faircoin-main`. */
+            network: z.ZodString;
+            txid: z.ZodString;
+            confirmations: z.ZodNumber;
+            /** When the anchoring transaction was broadcast (ms epoch). */
+            anchoredAt: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }, {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    }, {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    }>;
+    subjectDid: z.ZodString;
+    seq: z.ZodNumber;
+    headRecordId: z.ZodString;
+    leaf: z.ZodString;
+    leafIndex: z.ZodNumber;
+    /** Audit path, leaf-adjacent sibling first; empty for a single-leaf tree. */
+    proof: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    seq: number;
+    proof: string[];
+    headRecordId: string;
+    checkpoint: {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    };
+    subjectDid: string;
+    leaf: string;
+    leafIndex: number;
+}, {
+    seq: number;
+    proof: string[];
+    headRecordId: string;
+    checkpoint: {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    };
+    subjectDid: string;
+    leaf: string;
+    leafIndex: number;
+}>;
+/** A page of the checkpoint chain, oldest first, for walking `prevCheckpointHash`. */
+export declare const transparencyCheckpointListSchema: z.ZodObject<{
+    checkpoints: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        /** End of the committed period (ms epoch). */
+        periodEnd: z.ZodNumber;
+        /** Number of subjects (leaves) committed. */
+        treeSize: z.ZodNumber;
+        root: z.ZodString;
+        /** Hash of the previous checkpoint; `null` only at genesis. */
+        prevCheckpointHash: z.ZodNullable<z.ZodString>;
+        signatures: z.ZodArray<z.ZodObject<{
+            /** Uncompressed hex public key of the signer. */
+            publicKey: z.ZodString;
+            alg: z.ZodLiteral<"ES256K-DER-SHA256">;
+            /** DER-encoded hex secp256k1 signature over the checkpoint signing input. */
+            signature: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }, {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }>, "many">;
+        anchors: z.ZodArray<z.ZodObject<{
+            /** Chain/network identifier, e.g. `faircoin-main`. */
+            network: z.ZodString;
+            txid: z.ZodString;
+            confirmations: z.ZodNumber;
+            /** When the anchoring transaction was broadcast (ms epoch). */
+            anchoredAt: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }, {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    }, {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    checkpoints: {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    }[];
+}, {
+    checkpoints: {
+        index: number;
+        periodEnd: number;
+        treeSize: number;
+        root: string;
+        prevCheckpointHash: string | null;
+        signatures: {
+            signature: string;
+            publicKey: string;
+            alg: "ES256K-DER-SHA256";
+        }[];
+        anchors: {
+            network: string;
+            txid: string;
+            confirmations: number;
+            anchoredAt: number;
+        }[];
+    }[];
+}>;
+export type TransparencyCheckpointSignature = z.infer<typeof transparencyCheckpointSignatureSchema>;
+export type TransparencyAnchor = z.infer<typeof transparencyAnchorSchema>;
+export type TransparencyCheckpoint = z.infer<typeof transparencyCheckpointSchema>;
+export type TransparencyInclusionProof = z.infer<typeof transparencyInclusionProofSchema>;
+export type TransparencyCheckpointList = z.infer<typeof transparencyCheckpointListSchema>;