@oxy.so/contracts 4.17.0 → 4.21.0

package/dist/esm/safety.js

@@ -1,4 +1,12 @@
 import { z } from 'zod';
+import { accountActorChainSchema } from './accountSubject.js';
+// The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
+// its vocabularies are re-exported here so the root entry is unchanged.
+import { PURCHASE_APPROVAL_STATUSES, SAFETY_POLICY_VERSION, SUPERVISED_ACTIONS, SUPERVISION_CONSENT_VERSION, SUPERVISION_INVITATION_STATUSES, SUPERVISION_STATUSES, } from './client/safety.js';
+import { ORGANIZATION_TYPES } from './organizations.js';
+import { reauthProofSchema } from './signIn.js';
+import { userResponseSchema } from './userResponse.js';
+export { PURCHASE_APPROVAL_STATUSES, SAFETY_POLICY_VERSION, SUPERVISED_ACTIONS, SUPERVISION_CONSENT_VERSION, SUPERVISION_INVITATION_STATUSES, SUPERVISION_STATUSES, };
 /** The requester is authenticated by the bearer; applications cannot submit viewer IDs. */
 export const profileAccessInputSchema = z
     .object({ subjectAccountId: z.string().min(1).max(128) })
@@ -10,3 +18,418 @@ export const profileAccessDecisionSchema = z
     policyVersion: z.literal('1'),
 })
     .strict();
+export const SAFETY_DECISION_REASONS = [
+    'allowed',
+    'owner',
+    'public',
+    'private',
+    'blocked',
+    'unavailable',
+    'unsupported_consumer',
+    'contact_not_approved',
+    'mature_content',
+    'unrated_content',
+    'approval_required',
+];
+const accountId = z.string().min(1).max(128);
+const resourceId = z.string().trim().min(1).max(256);
+const uniqueIds = (max, min = 1) => z
+    .array(accountId)
+    .min(min)
+    .max(max)
+    .refine((ids) => new Set(ids).size === ids.length, 'Account IDs must be unique');
+export const safetyDecisionSchema = z
+    .object({
+    allowed: z.boolean(),
+    reason: z.enum(SAFETY_DECISION_REASONS),
+    policyVersion: z.literal(SAFETY_POLICY_VERSION),
+})
+    .strict();
+export const profileAccessBatchInputSchema = z
+    .object({ subjectAccountIds: uniqueIds(100) })
+    .strict();
+export const profileAccessBatchResponseSchema = z
+    .object({
+    items: z
+        .array(z
+        .object({
+        subjectAccountId: accountId,
+        decision: safetyDecisionSchema,
+    })
+        .strict())
+        .max(100),
+})
+    .strict();
+export const MESSAGE_ACCESS_MAX_RESOURCES = 100;
+export const MESSAGE_ACCESS_MAX_PARTICIPANTS = 1024;
+export const MESSAGE_ACCESS_MAX_SUPERVISED_PARTICIPANTS = 256;
+export const MESSAGE_ACCESS_MAX_PARTICIPANT_SLOTS = 4096;
+/** Leaves room for the original requester proof in a 512 KiB request. */
+export const MESSAGE_ACCESS_MAX_INPUT_BYTES = 448 * 1024;
+export const messageAccessInputSchema = z
+    .object({ participantAccountIds: uniqueIds(MESSAGE_ACCESS_MAX_PARTICIPANTS), resourceId })
+    .strict();
+export const contactAccessInputSchema = z.object({ targetAccountIds: uniqueIds(1000) }).strict();
+export const contactAccessResponseSchema = z
+    .object({
+    items: z
+        .array(z
+        .object({
+        targetAccountId: accountId,
+        decision: safetyDecisionSchema,
+    })
+        .strict())
+        .max(1000),
+})
+    .strict();
+export const CONTENT_CLASSIFICATIONS = ['general', 'mature', 'unrated'];
+export const contentAccessInputSchema = z
+    .object({
+    resourceId,
+    classification: z.enum(CONTENT_CLASSIFICATIONS),
+    authorAccountId: accountId.optional(),
+    audience: z.enum(['public', 'private', 'followers']).optional(),
+    applicationAudienceAllowed: z.boolean().optional(),
+    applicationResourceGrant: z.boolean().optional(),
+    operation: z.enum(['read', 'manage_own']).optional(),
+})
+    .strict()
+    .refine((item) => !item.audience ||
+    item.audience === 'public' ||
+    (!!item.authorAccountId && item.applicationAudienceAllowed !== undefined), 'Nonpublic content requires its authoritative author and application audience decision')
+    .refine((item) => item.operation !== 'manage_own' || !!item.authorAccountId, 'Own management requires its authoritative author');
+export const publicationPolicySchema = z
+    .object({
+    publicationAllowed: z.boolean(),
+    requiredAudience: z.literal('private').nullable(),
+    collaborationAllowed: z.boolean(),
+    federationAllowed: z.boolean(),
+    policyVersion: z.literal(SAFETY_POLICY_VERSION),
+})
+    .strict();
+export const publicationPoliciesInputSchema = z
+    .object({
+    authorAccountIds: z
+        .array(accountId)
+        .min(1)
+        .max(100)
+        .refine((ids) => new Set(ids).size === ids.length, 'Author IDs must be unique'),
+})
+    .strict();
+export const publicationPoliciesResponseSchema = z
+    .object({
+    items: z
+        .array(z.object({ authorAccountId: accountId, policy: publicationPolicySchema }).strict())
+        .max(100),
+})
+    .strict();
+export const contentAccessBatchInputSchema = z
+    .object({
+    items: z
+        .array(contentAccessInputSchema)
+        .min(1)
+        .max(100)
+        .refine((items) => new Set(items.map((item) => item.resourceId)).size === items.length, 'Resource IDs must be unique'),
+})
+    .strict();
+export const contentAccessBatchResponseSchema = z
+    .object({
+    items: z
+        .array(z
+        .object({
+        resourceId,
+        decision: safetyDecisionSchema,
+    })
+        .strict())
+        .max(100),
+})
+    .strict();
+/** A reviewed background consumer may decide delivery, but never authenticate as the sender. */
+export const deliveryAccessInputSchema = messageAccessInputSchema
+    .extend({ senderAccountId: accountId })
+    .strict();
+/** Count repeated participants across resources too: this bounds both graph and pair evaluations. */
+const messageBatch = (schema) => z
+    .object({ items: z.array(schema).min(1).max(MESSAGE_ACCESS_MAX_RESOURCES) })
+    .strict()
+    .refine((value) => new Set(value.items.map((item) => item.resourceId)).size === value.items.length, 'Resource IDs must be unique')
+    .refine((value) => value.items.reduce((total, item) => total + item.participantAccountIds.length, 0) <=
+    MESSAGE_ACCESS_MAX_PARTICIPANT_SLOTS, 'Participant budget exceeded')
+    .refine((value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <=
+    MESSAGE_ACCESS_MAX_INPUT_BYTES, 'Message batch byte budget exceeded');
+export const messageAccessBatchInputSchema = messageBatch(messageAccessInputSchema);
+export const deliveryAccessBatchInputSchema = messageBatch(deliveryAccessInputSchema);
+export const messageAccessBatchResponseSchema = contentAccessBatchResponseSchema;
+/** Live socket-recipient proof; a request ID correlates the result and never identifies an account. */
+export const messagingSessionsInputSchema = z
+    .object({
+    items: z
+        .array(z
+        .object({
+        requestId: resourceId,
+        accessToken: z.string().min(1).max(16384),
+    })
+        .strict())
+        .min(1)
+        .max(100),
+})
+    .strict()
+    .refine((value) => new Set(value.items.map((item) => item.requestId)).size === value.items.length, 'Request IDs must be unique')
+    .refine((value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <= MESSAGE_ACCESS_MAX_INPUT_BYTES, 'Session proof byte budget exceeded');
+export const messagingSessionsResponseSchema = z
+    .object({
+    items: z
+        .array(z.discriminatedUnion('allowed', [
+        z.object({ requestId: resourceId, allowed: z.literal(true), accountId }).strict(),
+        z.object({ requestId: resourceId, allowed: z.literal(false) }).strict(),
+    ]))
+        .max(100),
+})
+    .strict();
+export const safetyRequesterSchema = z.union([
+    z.object({ accessToken: z.string().min(1).max(16384).nullable() }).strict(),
+    z.object({ connectionToken: z.string().min(1).max(16384) }).strict(),
+]);
+export const supervisionSchema = z
+    .object({
+    childAccountId: accountId,
+    guardianAccountId: accountId.nullable(),
+    status: z.enum(SUPERVISION_STATUSES),
+    policyVersion: z.literal(SAFETY_POLICY_VERSION),
+    consentVersion: z.literal(SUPERVISION_CONSENT_VERSION),
+    createdAt: z.string().datetime(),
+})
+    .strict();
+export const supervisionInvitationSchema = z
+    .object({
+    id: accountId,
+    childAccountId: accountId,
+    guardianAccountId: accountId,
+    status: z.enum(SUPERVISION_INVITATION_STATUSES),
+    expiresAt: z.string().datetime(),
+    consentVersion: z.literal(SUPERVISION_CONSENT_VERSION),
+    createdAt: z.string().datetime(),
+})
+    .strict();
+export const supervisionContactSchema = z
+    .object({
+    childAccountId: accountId,
+    contactAccountId: accountId,
+    approvedAt: z.string().datetime(),
+})
+    .strict();
+export const supervisionStateSchema = z
+    .object({
+    self: supervisionSchema.nullable(),
+    children: z.array(supervisionSchema).max(100),
+    invitations: z.array(supervisionInvitationSchema).max(100),
+})
+    .strict();
+export const supervisionContactsResponseSchema = z
+    .object({ items: z.array(supervisionContactSchema).max(1000) })
+    .strict();
+const fingerprint = z.string().regex(/^[a-f0-9]{64}$/);
+const minorUnits = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const purchaseApprovalLineSchema = z
+    .object({
+    itemReference: resourceId,
+    title: z.string().trim().min(1).max(300),
+    optionsText: z.string().trim().max(300),
+    merchantAccountId: accountId,
+    quantity: z.number().int().min(1).max(1000000),
+    unitAmountMinor: minorUnits,
+    lineAmountMinor: minorUnits,
+})
+    .strict();
+const purchaseEffectsObject = z
+    .object({
+    operationId: resourceId,
+    resourceId,
+    cartFingerprint: fingerprint,
+    summary: z.string().trim().min(1).max(300),
+    merchantAccountIds: z
+        .array(accountId)
+        .min(1)
+        .max(100)
+        .refine((ids) => new Set(ids).size === ids.length, 'Merchant accounts must be unique')
+        .transform((ids) => [...ids].sort()),
+    lineItems: z.array(purchaseApprovalLineSchema).min(1).max(200),
+    shippingMinor: minorUnits,
+    taxMinor: minorUnits,
+    discountMinor: minorUnits,
+    roundingAdjustmentMinor: z
+        .number()
+        .int()
+        .min(-Number.MAX_SAFE_INTEGER)
+        .max(Number.MAX_SAFE_INTEGER),
+    paymentFingerprint: fingerprint,
+    amountMinor: minorUnits,
+    currency: z.string().regex(/^[A-Z]{3}$/),
+    expiresAt: z.string().datetime(),
+})
+    .strict();
+function validatePurchaseEvidence(value, ctx) {
+    const merchants = new Set(value.merchantAccountIds);
+    const references = new Set();
+    for (const line of value.lineItems) {
+        const key = `${line.merchantAccountId}:${line.itemReference}`;
+        if (!merchants.has(line.merchantAccountId) || references.has(key))
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'Purchase lines must name an included merchant and unique item reference',
+            });
+        references.add(key);
+    }
+    if (merchants.size !== new Set(value.lineItems.map((line) => line.merchantAccountId)).size)
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Every merchant must have an approval line',
+        });
+    const total = value.lineItems.reduce((sum, line) => sum + BigInt(line.lineAmountMinor), 0n) +
+        BigInt(value.shippingMinor) +
+        BigInt(value.taxMinor) -
+        BigInt(value.discountMinor) +
+        BigInt(value.roundingAdjustmentMinor);
+    if (total < 0n || total > BigInt(Number.MAX_SAFE_INTEGER) || total !== BigInt(value.amountMinor))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Approval evidence must equal the exact payment total',
+        });
+    if (Math.abs(value.roundingAdjustmentMinor) >
+        value.lineItems.length + 3 * value.merchantAccountIds.length)
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Rounding adjustment exceeds the bounded conversion stages',
+        });
+}
+export const purchaseEffectsSchema = purchaseEffectsObject.superRefine(validatePurchaseEvidence);
+const purchaseApprovalFields = {
+    id: accountId,
+    childAccountId: accountId,
+    applicationId: accountId,
+    status: z.enum(PURCHASE_APPROVAL_STATUSES),
+    createdAt: z.string().datetime(),
+    receiptReference: z.string().max(512).nullable(),
+};
+export const purchaseApprovalSchema = purchaseEffectsObject
+    .extend(purchaseApprovalFields)
+    .strict()
+    .superRefine(validatePurchaseEvidence);
+export const purchaseApprovalSummarySchema = purchaseEffectsObject
+    .omit({ lineItems: true })
+    .extend(purchaseApprovalFields)
+    .strict();
+export const purchaseApprovalListSchema = z
+    .object({
+    items: z.array(purchaseApprovalSummarySchema).max(100),
+    nextCursor: z.string().nullable(),
+})
+    .strict();
+export const reservePurchaseSchema = purchaseEffectsObject
+    .extend({ approvalId: accountId })
+    .strict()
+    .superRefine(validatePurchaseEvidence);
+export const confirmPurchaseSchema = z
+    .object({
+    approvalId: accountId,
+    operationId: resourceId,
+    receiptReference: z.string().trim().min(1).max(512),
+})
+    .strict();
+export const cancelPurchaseSchema = confirmPurchaseSchema.omit({ receiptReference: true });
+export const SAFETY_ERROR_CODES = [
+    'bad_request',
+    'validation_failed',
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'conflict',
+    'reauth_required',
+    'limit_reached',
+    'service_unavailable',
+    'rate_limited',
+];
+export const safetyErrorSchema = z
+    .object({ error: z.object({ code: z.enum(SAFETY_ERROR_CODES), message: z.string() }).strict() })
+    .strict();
+export const supervisionInviteInputSchema = z
+    .object({
+    guardianAccountId: accountId,
+    consentVersion: z.literal(SUPERVISION_CONSENT_VERSION),
+    reauth: reauthProofSchema,
+})
+    .strict();
+export const supervisionAcceptInputSchema = z
+    .object({ consentVersion: z.literal(SUPERVISION_CONSENT_VERSION), reauth: reauthProofSchema })
+    .strict();
+export const supervisionContactInputSchema = z
+    .object({ childAccountId: accountId, contactAccountId: accountId, reauth: reauthProofSchema })
+    .strict();
+export const supervisionReviewInputSchema = z
+    .object({
+    childAccountId: accountId,
+    action: z.enum(['end', 'transfer']),
+    guardianAccountId: accountId.optional(),
+    evidenceReference: z.string().trim().min(1).max(2048),
+    reauth: reauthProofSchema,
+})
+    .strict();
+export const purchaseReviewInputSchema = z
+    .object({ decision: z.enum(['approved', 'rejected']), reauth: reauthProofSchema })
+    .strict();
+export const safetySessionInputSchema = z
+    .object({
+    sessionId: accountId,
+    accessToken: z.string().min(1).max(16384),
+    action: z.enum(SUPERVISED_ACTIONS),
+})
+    .strict();
+export const safetySessionValidationSchema = z
+    .object({
+    valid: z.literal(true),
+    sessionId: accountId,
+    expiresAt: z.string().datetime(),
+    lastActivity: z.string().datetime(),
+    user: userResponseSchema,
+    actor: accountActorChainSchema,
+})
+    .strict();
+/** Minimal identity for the authenticated account's supervision management, never profile details. */
+export const safetyPersonSchema = z
+    .object({ accountId, username: z.string().nullable(), displayName: z.string().nullable() })
+    .strict();
+export const safetyPeopleInputSchema = z.union([
+    z.object({ query: z.string().trim().min(2).max(100) }).strict(),
+    z.object({ accountIds: uniqueIds(100) }).strict(),
+]);
+export const safetyPeopleResponseSchema = z
+    .object({ items: z.array(safetyPersonSchema).max(100) })
+    .strict();
+/** Existing public employer identity only; never directory content or management authority. */
+export const safetyOrganizationIdentitySchema = z
+    .object({
+    accountId,
+    username: z.string().nullable(),
+    name: z.string(),
+    organizationType: z.enum(ORGANIZATION_TYPES),
+})
+    .strict();
+export const safetyOrganizationsInputSchema = z.union([
+    z
+        .object({
+        query: z.string().trim().min(1).max(100),
+        limit: z.number().int().min(1).max(20).optional(),
+    })
+        .strict(),
+    z.object({ ids: uniqueIds(100) }).strict(),
+]);
+export const safetyOrganizationsResponseSchema = z
+    .object({
+    items: z
+        .array(z
+        .object({ requestedAccountId: accountId, organization: safetyOrganizationIdentitySchema })
+        .strict())
+        .max(100),
+    missingIds: z.array(accountId).max(100),
+})
+    .strict();

package/dist/esm/serviceToken.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+/** Omitted means the existing grant; an explicit set only narrows that authority. */
+export const serviceTokenScopesSchema = z
+    .array(z.string().trim().min(1).max(128))
+    .min(1)
+    .max(100)
+    .refine((scopes) => new Set(scopes).size === scopes.length, 'Requested scopes must be unique')
+    .transform((scopes) => [...scopes].sort());
+export const serviceTokenOptionsSchema = z
+    .object({ scopes: serviceTokenScopesSchema.optional() })
+    .strict();

package/dist/types/accountAccess.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Wire contract for `GET /internal/accounts/:accountId/access/:userId`: Oxy
+ * answers a trusted first-party service's question "may this person act FOR
+ * that account, and with what?" with no session of that person in the request.
+ *
+ * It exists for the account Oxy never lets anybody act AS: a `channel`
+ * ({@link isDelegatedActAsEligibleKind} refuses it). An app publishes to a
+ * channel with ITS OWN credential, on behalf of a member Oxy vouches for here,
+ * so nobody holds a bearer that speaks as the channel. A long-running import
+ * (Oxy Move) has only a service token and `X-Oxy-User-Id`, which the
+ * user-facing `GET /accounts/:id/members` refuses; this is its answer.
+ *
+ * Needs a service token whose application is platform-trusted AND holds the
+ * privileged {@link ACCOUNTS_MEMBERSHIP_READ_SCOPE}. The answer is always 200:
+ * `access` is `null` for no active membership, an archived account, an unknown
+ * account and an unclaimed directory account alike. Callers must treat every
+ * other status as a refusal (fail closed), and must not cache the answer longer
+ * than the action it authorizes.
+ *
+ * Platform-agnostic — zod only.
+ */
+import { z } from 'zod';
+/**
+ * The scope the endpoint requires.
+ *
+ * Privileged (staff-granted). Channel membership is sensitive because a channel
+ * is anonymous: its members are the people behind a voice that is published
+ * without their names, and "is this person a member of that channel" is
+ * exactly the fact the channel exists to withhold.
+ */
+export declare const ACCOUNTS_MEMBERSHIP_READ_SCOPE: "accounts:membership:read";
+/**
+ * Where the access comes from.
+ *
+ * - `self` — the person IS the account (a personal account asked about itself).
+ * - `direct` — an active membership row on the account.
+ * - `inherited` — an active, cascading membership on an ancestor account.
+ */
+export declare const ACCOUNT_ACCESS_SOURCES: readonly ["self", "direct", "inherited"];
+export type AccountAccessSource = (typeof ACCOUNT_ACCESS_SOURCES)[number];
+export declare const accountAccessSourceSchema: z.ZodEnum<["self", "direct", "inherited"]>;
+/**
+ * One person's EFFECTIVE access over one account.
+ *
+ * `role` and `permissions` are strings rather than closed enums on purpose: the
+ * role and permission vocabularies are the API's, they grow, and a consumer
+ * pinned to an older contracts release must keep reading new ones. Gate on
+ * `permissions` (the role's baseline adjusted by per-member grants and
+ * revokes), never on `role`.
+ */
+export declare const accountAccessGrantSchema: z.ZodObject<{
+    role: z.ZodString;
+    permissions: z.ZodArray<z.ZodString, "many">;
+    /** Only an active membership grants access, so this is the one value. */
+    status: z.ZodLiteral<"active">;
+    source: z.ZodEnum<["self", "direct", "inherited"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "active";
+    role: string;
+    permissions: string[];
+    source: "self" | "direct" | "inherited";
+}, {
+    status: "active";
+    role: string;
+    permissions: string[];
+    source: "self" | "direct" | "inherited";
+}>;
+export type AccountAccessGrant = z.infer<typeof accountAccessGrantSchema>;
+export declare const accountAccessVerdictSchema: z.ZodEffects<z.ZodObject<{
+    accountId: z.ZodString;
+    /** `null` when no such account exists. */
+    kind: z.ZodNullable<z.ZodEnum<["personal", "organization", "project", "bot", "channel"]>>;
+    /** `null` means: this person may not act for this account. */
+    access: z.ZodNullable<z.ZodObject<{
+        role: z.ZodString;
+        permissions: z.ZodArray<z.ZodString, "many">;
+        /** Only an active membership grants access, so this is the one value. */
+        status: z.ZodLiteral<"active">;
+        source: z.ZodEnum<["self", "direct", "inherited"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    }, {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}>, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}>;
+export type AccountAccessVerdict = z.infer<typeof accountAccessVerdictSchema>;

package/dist/types/accountEmail.d.ts

@@ -24,11 +24,11 @@ export declare const emailVerificationStartRequestSchema: z.ZodObject<{
     purpose: z.ZodLiteral<"signup">;
     email: z.ZodString;
 }, "strict", z.ZodTypeAny, {
-    purpose: "signup";
     email: string;
-}, {
     purpose: "signup";
+}, {
     email: string;
+    purpose: "signup";
 }>;
 export type EmailVerificationStartRequest = z.infer<typeof emailVerificationStartRequestSchema>;
 export interface EmailVerificationStartResponse {