@oxy.so/contracts 4.17.0 → 4.22.0

package/dist/cjs/safety.js

@@ -1,7 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.profileAccessDecisionSchema = exports.profileAccessInputSchema = void 0;
+exports.supervisionInviteInputSchema = exports.safetyErrorSchema = exports.SAFETY_ERROR_CODES = exports.cancelPurchaseSchema = exports.confirmPurchaseSchema = exports.reservePurchaseSchema = exports.purchaseApprovalListSchema = exports.purchaseApprovalSummarySchema = exports.purchaseApprovalSchema = exports.purchaseEffectsSchema = exports.purchaseApprovalLineSchema = exports.supervisionContactsResponseSchema = exports.supervisionStateSchema = exports.supervisionContactSchema = exports.supervisionInvitationSchema = exports.supervisionSchema = exports.safetyRequesterSchema = exports.messagingSessionsResponseSchema = exports.messagingSessionsInputSchema = exports.messageAccessBatchResponseSchema = exports.deliveryAccessBatchInputSchema = exports.messageAccessBatchInputSchema = exports.deliveryAccessInputSchema = exports.contentAccessBatchResponseSchema = exports.contentAccessBatchInputSchema = exports.publicationPoliciesResponseSchema = exports.publicationPoliciesInputSchema = exports.publicationPolicySchema = exports.contentAccessInputSchema = exports.CONTENT_CLASSIFICATIONS = exports.contactAccessResponseSchema = exports.contactAccessInputSchema = exports.messageAccessInputSchema = exports.MESSAGE_ACCESS_MAX_INPUT_BYTES = exports.MESSAGE_ACCESS_MAX_PARTICIPANT_SLOTS = exports.MESSAGE_ACCESS_MAX_SUPERVISED_PARTICIPANTS = exports.MESSAGE_ACCESS_MAX_PARTICIPANTS = exports.MESSAGE_ACCESS_MAX_RESOURCES = exports.profileAccessBatchResponseSchema = exports.profileAccessBatchInputSchema = exports.safetyDecisionSchema = exports.SAFETY_DECISION_REASONS = exports.profileAccessDecisionSchema = exports.profileAccessInputSchema = exports.SUPERVISION_STATUSES = exports.SUPERVISION_INVITATION_STATUSES = exports.SUPERVISION_CONSENT_VERSION = exports.SUPERVISED_ACTIONS = exports.SAFETY_POLICY_VERSION = exports.PURCHASE_APPROVAL_STATUSES = void 0;
+exports.safetyOrganizationsResponseSchema = exports.safetyOrganizationsInputSchema = exports.safetyOrganizationIdentitySchema = exports.safetyPeopleResponseSchema = exports.safetyPeopleInputSchema = exports.safetyPersonSchema = exports.safetySessionValidationSchema = exports.safetySessionInputSchema = exports.purchaseReviewInputSchema = exports.supervisionReviewInputSchema = exports.supervisionContactInputSchema = exports.supervisionAcceptInputSchema = void 0;
 const zod_1 = require("zod");
+const accountSubject_1 = require("./accountSubject");
+// 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.
+const safety_1 = require("./client/safety");
+Object.defineProperty(exports, "PURCHASE_APPROVAL_STATUSES", { enumerable: true, get: function () { return safety_1.PURCHASE_APPROVAL_STATUSES; } });
+Object.defineProperty(exports, "SAFETY_POLICY_VERSION", { enumerable: true, get: function () { return safety_1.SAFETY_POLICY_VERSION; } });
+Object.defineProperty(exports, "SUPERVISED_ACTIONS", { enumerable: true, get: function () { return safety_1.SUPERVISED_ACTIONS; } });
+Object.defineProperty(exports, "SUPERVISION_CONSENT_VERSION", { enumerable: true, get: function () { return safety_1.SUPERVISION_CONSENT_VERSION; } });
+Object.defineProperty(exports, "SUPERVISION_INVITATION_STATUSES", { enumerable: true, get: function () { return safety_1.SUPERVISION_INVITATION_STATUSES; } });
+Object.defineProperty(exports, "SUPERVISION_STATUSES", { enumerable: true, get: function () { return safety_1.SUPERVISION_STATUSES; } });
+const organizations_1 = require("./organizations");
+const signIn_1 = require("./signIn");
+const userResponse_1 = require("./userResponse");
 /** The requester is authenticated by the bearer; applications cannot submit viewer IDs. */
 exports.profileAccessInputSchema = zod_1.z
     .object({ subjectAccountId: zod_1.z.string().min(1).max(128) })
@@ -13,3 +27,418 @@ exports.profileAccessDecisionSchema = zod_1.z
     policyVersion: zod_1.z.literal('1'),
 })
     .strict();
+exports.SAFETY_DECISION_REASONS = [
+    'allowed',
+    'owner',
+    'public',
+    'private',
+    'blocked',
+    'unavailable',
+    'unsupported_consumer',
+    'contact_not_approved',
+    'mature_content',
+    'unrated_content',
+    'approval_required',
+];
+const accountId = zod_1.z.string().min(1).max(128);
+const resourceId = zod_1.z.string().trim().min(1).max(256);
+const uniqueIds = (max, min = 1) => zod_1.z
+    .array(accountId)
+    .min(min)
+    .max(max)
+    .refine((ids) => new Set(ids).size === ids.length, 'Account IDs must be unique');
+exports.safetyDecisionSchema = zod_1.z
+    .object({
+    allowed: zod_1.z.boolean(),
+    reason: zod_1.z.enum(exports.SAFETY_DECISION_REASONS),
+    policyVersion: zod_1.z.literal(safety_1.SAFETY_POLICY_VERSION),
+})
+    .strict();
+exports.profileAccessBatchInputSchema = zod_1.z
+    .object({ subjectAccountIds: uniqueIds(100) })
+    .strict();
+exports.profileAccessBatchResponseSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(zod_1.z
+        .object({
+        subjectAccountId: accountId,
+        decision: exports.safetyDecisionSchema,
+    })
+        .strict())
+        .max(100),
+})
+    .strict();
+exports.MESSAGE_ACCESS_MAX_RESOURCES = 100;
+exports.MESSAGE_ACCESS_MAX_PARTICIPANTS = 1024;
+exports.MESSAGE_ACCESS_MAX_SUPERVISED_PARTICIPANTS = 256;
+exports.MESSAGE_ACCESS_MAX_PARTICIPANT_SLOTS = 4096;
+/** Leaves room for the original requester proof in a 512 KiB request. */
+exports.MESSAGE_ACCESS_MAX_INPUT_BYTES = 448 * 1024;
+exports.messageAccessInputSchema = zod_1.z
+    .object({ participantAccountIds: uniqueIds(exports.MESSAGE_ACCESS_MAX_PARTICIPANTS), resourceId })
+    .strict();
+exports.contactAccessInputSchema = zod_1.z.object({ targetAccountIds: uniqueIds(1000) }).strict();
+exports.contactAccessResponseSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(zod_1.z
+        .object({
+        targetAccountId: accountId,
+        decision: exports.safetyDecisionSchema,
+    })
+        .strict())
+        .max(1000),
+})
+    .strict();
+exports.CONTENT_CLASSIFICATIONS = ['general', 'mature', 'unrated'];
+exports.contentAccessInputSchema = zod_1.z
+    .object({
+    resourceId,
+    classification: zod_1.z.enum(exports.CONTENT_CLASSIFICATIONS),
+    authorAccountId: accountId.optional(),
+    audience: zod_1.z.enum(['public', 'private', 'followers']).optional(),
+    applicationAudienceAllowed: zod_1.z.boolean().optional(),
+    applicationResourceGrant: zod_1.z.boolean().optional(),
+    operation: zod_1.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');
+exports.publicationPolicySchema = zod_1.z
+    .object({
+    publicationAllowed: zod_1.z.boolean(),
+    requiredAudience: zod_1.z.literal('private').nullable(),
+    collaborationAllowed: zod_1.z.boolean(),
+    federationAllowed: zod_1.z.boolean(),
+    policyVersion: zod_1.z.literal(safety_1.SAFETY_POLICY_VERSION),
+})
+    .strict();
+exports.publicationPoliciesInputSchema = zod_1.z
+    .object({
+    authorAccountIds: zod_1.z
+        .array(accountId)
+        .min(1)
+        .max(100)
+        .refine((ids) => new Set(ids).size === ids.length, 'Author IDs must be unique'),
+})
+    .strict();
+exports.publicationPoliciesResponseSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(zod_1.z.object({ authorAccountId: accountId, policy: exports.publicationPolicySchema }).strict())
+        .max(100),
+})
+    .strict();
+exports.contentAccessBatchInputSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(exports.contentAccessInputSchema)
+        .min(1)
+        .max(100)
+        .refine((items) => new Set(items.map((item) => item.resourceId)).size === items.length, 'Resource IDs must be unique'),
+})
+    .strict();
+exports.contentAccessBatchResponseSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(zod_1.z
+        .object({
+        resourceId,
+        decision: exports.safetyDecisionSchema,
+    })
+        .strict())
+        .max(100),
+})
+    .strict();
+/** A reviewed background consumer may decide delivery, but never authenticate as the sender. */
+exports.deliveryAccessInputSchema = exports.messageAccessInputSchema
+    .extend({ senderAccountId: accountId })
+    .strict();
+/** Count repeated participants across resources too: this bounds both graph and pair evaluations. */
+const messageBatch = (schema) => zod_1.z
+    .object({ items: zod_1.z.array(schema).min(1).max(exports.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) <=
+    exports.MESSAGE_ACCESS_MAX_PARTICIPANT_SLOTS, 'Participant budget exceeded')
+    .refine((value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <=
+    exports.MESSAGE_ACCESS_MAX_INPUT_BYTES, 'Message batch byte budget exceeded');
+exports.messageAccessBatchInputSchema = messageBatch(exports.messageAccessInputSchema);
+exports.deliveryAccessBatchInputSchema = messageBatch(exports.deliveryAccessInputSchema);
+exports.messageAccessBatchResponseSchema = exports.contentAccessBatchResponseSchema;
+/** Live socket-recipient proof; a request ID correlates the result and never identifies an account. */
+exports.messagingSessionsInputSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(zod_1.z
+        .object({
+        requestId: resourceId,
+        accessToken: zod_1.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 <= exports.MESSAGE_ACCESS_MAX_INPUT_BYTES, 'Session proof byte budget exceeded');
+exports.messagingSessionsResponseSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(zod_1.z.discriminatedUnion('allowed', [
+        zod_1.z.object({ requestId: resourceId, allowed: zod_1.z.literal(true), accountId }).strict(),
+        zod_1.z.object({ requestId: resourceId, allowed: zod_1.z.literal(false) }).strict(),
+    ]))
+        .max(100),
+})
+    .strict();
+exports.safetyRequesterSchema = zod_1.z.union([
+    zod_1.z.object({ accessToken: zod_1.z.string().min(1).max(16384).nullable() }).strict(),
+    zod_1.z.object({ connectionToken: zod_1.z.string().min(1).max(16384) }).strict(),
+]);
+exports.supervisionSchema = zod_1.z
+    .object({
+    childAccountId: accountId,
+    guardianAccountId: accountId.nullable(),
+    status: zod_1.z.enum(safety_1.SUPERVISION_STATUSES),
+    policyVersion: zod_1.z.literal(safety_1.SAFETY_POLICY_VERSION),
+    consentVersion: zod_1.z.literal(safety_1.SUPERVISION_CONSENT_VERSION),
+    createdAt: zod_1.z.string().datetime(),
+})
+    .strict();
+exports.supervisionInvitationSchema = zod_1.z
+    .object({
+    id: accountId,
+    childAccountId: accountId,
+    guardianAccountId: accountId,
+    status: zod_1.z.enum(safety_1.SUPERVISION_INVITATION_STATUSES),
+    expiresAt: zod_1.z.string().datetime(),
+    consentVersion: zod_1.z.literal(safety_1.SUPERVISION_CONSENT_VERSION),
+    createdAt: zod_1.z.string().datetime(),
+})
+    .strict();
+exports.supervisionContactSchema = zod_1.z
+    .object({
+    childAccountId: accountId,
+    contactAccountId: accountId,
+    approvedAt: zod_1.z.string().datetime(),
+})
+    .strict();
+exports.supervisionStateSchema = zod_1.z
+    .object({
+    self: exports.supervisionSchema.nullable(),
+    children: zod_1.z.array(exports.supervisionSchema).max(100),
+    invitations: zod_1.z.array(exports.supervisionInvitationSchema).max(100),
+})
+    .strict();
+exports.supervisionContactsResponseSchema = zod_1.z
+    .object({ items: zod_1.z.array(exports.supervisionContactSchema).max(1000) })
+    .strict();
+const fingerprint = zod_1.z.string().regex(/^[a-f0-9]{64}$/);
+const minorUnits = zod_1.z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+exports.purchaseApprovalLineSchema = zod_1.z
+    .object({
+    itemReference: resourceId,
+    title: zod_1.z.string().trim().min(1).max(300),
+    optionsText: zod_1.z.string().trim().max(300),
+    merchantAccountId: accountId,
+    quantity: zod_1.z.number().int().min(1).max(1000000),
+    unitAmountMinor: minorUnits,
+    lineAmountMinor: minorUnits,
+})
+    .strict();
+const purchaseEffectsObject = zod_1.z
+    .object({
+    operationId: resourceId,
+    resourceId,
+    cartFingerprint: fingerprint,
+    summary: zod_1.z.string().trim().min(1).max(300),
+    merchantAccountIds: zod_1.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: zod_1.z.array(exports.purchaseApprovalLineSchema).min(1).max(200),
+    shippingMinor: minorUnits,
+    taxMinor: minorUnits,
+    discountMinor: minorUnits,
+    roundingAdjustmentMinor: zod_1.z
+        .number()
+        .int()
+        .min(-Number.MAX_SAFE_INTEGER)
+        .max(Number.MAX_SAFE_INTEGER),
+    paymentFingerprint: fingerprint,
+    amountMinor: minorUnits,
+    currency: zod_1.z.string().regex(/^[A-Z]{3}$/),
+    expiresAt: zod_1.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: zod_1.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: zod_1.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: zod_1.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: zod_1.z.ZodIssueCode.custom,
+            message: 'Rounding adjustment exceeds the bounded conversion stages',
+        });
+}
+exports.purchaseEffectsSchema = purchaseEffectsObject.superRefine(validatePurchaseEvidence);
+const purchaseApprovalFields = {
+    id: accountId,
+    childAccountId: accountId,
+    applicationId: accountId,
+    status: zod_1.z.enum(safety_1.PURCHASE_APPROVAL_STATUSES),
+    createdAt: zod_1.z.string().datetime(),
+    receiptReference: zod_1.z.string().max(512).nullable(),
+};
+exports.purchaseApprovalSchema = purchaseEffectsObject
+    .extend(purchaseApprovalFields)
+    .strict()
+    .superRefine(validatePurchaseEvidence);
+exports.purchaseApprovalSummarySchema = purchaseEffectsObject
+    .omit({ lineItems: true })
+    .extend(purchaseApprovalFields)
+    .strict();
+exports.purchaseApprovalListSchema = zod_1.z
+    .object({
+    items: zod_1.z.array(exports.purchaseApprovalSummarySchema).max(100),
+    nextCursor: zod_1.z.string().nullable(),
+})
+    .strict();
+exports.reservePurchaseSchema = purchaseEffectsObject
+    .extend({ approvalId: accountId })
+    .strict()
+    .superRefine(validatePurchaseEvidence);
+exports.confirmPurchaseSchema = zod_1.z
+    .object({
+    approvalId: accountId,
+    operationId: resourceId,
+    receiptReference: zod_1.z.string().trim().min(1).max(512),
+})
+    .strict();
+exports.cancelPurchaseSchema = exports.confirmPurchaseSchema.omit({ receiptReference: true });
+exports.SAFETY_ERROR_CODES = [
+    'bad_request',
+    'validation_failed',
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'conflict',
+    'reauth_required',
+    'limit_reached',
+    'service_unavailable',
+    'rate_limited',
+];
+exports.safetyErrorSchema = zod_1.z
+    .object({ error: zod_1.z.object({ code: zod_1.z.enum(exports.SAFETY_ERROR_CODES), message: zod_1.z.string() }).strict() })
+    .strict();
+exports.supervisionInviteInputSchema = zod_1.z
+    .object({
+    guardianAccountId: accountId,
+    consentVersion: zod_1.z.literal(safety_1.SUPERVISION_CONSENT_VERSION),
+    reauth: signIn_1.reauthProofSchema,
+})
+    .strict();
+exports.supervisionAcceptInputSchema = zod_1.z
+    .object({ consentVersion: zod_1.z.literal(safety_1.SUPERVISION_CONSENT_VERSION), reauth: signIn_1.reauthProofSchema })
+    .strict();
+exports.supervisionContactInputSchema = zod_1.z
+    .object({ childAccountId: accountId, contactAccountId: accountId, reauth: signIn_1.reauthProofSchema })
+    .strict();
+exports.supervisionReviewInputSchema = zod_1.z
+    .object({
+    childAccountId: accountId,
+    action: zod_1.z.enum(['end', 'transfer']),
+    guardianAccountId: accountId.optional(),
+    evidenceReference: zod_1.z.string().trim().min(1).max(2048),
+    reauth: signIn_1.reauthProofSchema,
+})
+    .strict();
+exports.purchaseReviewInputSchema = zod_1.z
+    .object({ decision: zod_1.z.enum(['approved', 'rejected']), reauth: signIn_1.reauthProofSchema })
+    .strict();
+exports.safetySessionInputSchema = zod_1.z
+    .object({
+    sessionId: accountId,
+    accessToken: zod_1.z.string().min(1).max(16384),
+    action: zod_1.z.enum(safety_1.SUPERVISED_ACTIONS),
+})
+    .strict();
+exports.safetySessionValidationSchema = zod_1.z
+    .object({
+    valid: zod_1.z.literal(true),
+    sessionId: accountId,
+    expiresAt: zod_1.z.string().datetime(),
+    lastActivity: zod_1.z.string().datetime(),
+    user: userResponse_1.userResponseSchema,
+    actor: accountSubject_1.accountActorChainSchema,
+})
+    .strict();
+/** Minimal identity for the authenticated account's supervision management, never profile details. */
+exports.safetyPersonSchema = zod_1.z
+    .object({ accountId, username: zod_1.z.string().nullable(), displayName: zod_1.z.string().nullable() })
+    .strict();
+exports.safetyPeopleInputSchema = zod_1.z.union([
+    zod_1.z.object({ query: zod_1.z.string().trim().min(2).max(100) }).strict(),
+    zod_1.z.object({ accountIds: uniqueIds(100) }).strict(),
+]);
+exports.safetyPeopleResponseSchema = zod_1.z
+    .object({ items: zod_1.z.array(exports.safetyPersonSchema).max(100) })
+    .strict();
+/** Existing public employer identity only; never directory content or management authority. */
+exports.safetyOrganizationIdentitySchema = zod_1.z
+    .object({
+    accountId,
+    username: zod_1.z.string().nullable(),
+    name: zod_1.z.string(),
+    organizationType: zod_1.z.enum(organizations_1.ORGANIZATION_TYPES),
+})
+    .strict();
+exports.safetyOrganizationsInputSchema = zod_1.z.union([
+    zod_1.z
+        .object({
+        query: zod_1.z.string().trim().min(1).max(100),
+        limit: zod_1.z.number().int().min(1).max(20).optional(),
+    })
+        .strict(),
+    zod_1.z.object({ ids: uniqueIds(100) }).strict(),
+]);
+exports.safetyOrganizationsResponseSchema = zod_1.z
+    .object({
+    items: zod_1.z
+        .array(zod_1.z
+        .object({ requestedAccountId: accountId, organization: exports.safetyOrganizationIdentitySchema })
+        .strict())
+        .max(100),
+    missingIds: zod_1.z.array(accountId).max(100),
+})
+    .strict();

package/dist/cjs/serviceToken.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceTokenOptionsSchema = exports.serviceTokenScopesSchema = void 0;
+const zod_1 = require("zod");
+/** Omitted means the existing grant; an explicit set only narrows that authority. */
+exports.serviceTokenScopesSchema = zod_1.z
+    .array(zod_1.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());
+exports.serviceTokenOptionsSchema = zod_1.z
+    .object({ scopes: exports.serviceTokenScopesSchema.optional() })
+    .strict();

package/dist/esm/accountAccess.js

@@ -0,0 +1,69 @@
+/**
+ * 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';
+import { accountKindSchema } from './accountGraph.js';
+/**
+ * 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 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 const ACCOUNT_ACCESS_SOURCES = ['self', 'direct', 'inherited'];
+export const accountAccessSourceSchema = z.enum(ACCOUNT_ACCESS_SOURCES);
+/**
+ * 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 const accountAccessGrantSchema = z.object({
+    role: z.string().min(1),
+    permissions: z.array(z.string().min(1)),
+    /** Only an active membership grants access, so this is the one value. */
+    status: z.literal('active'),
+    source: accountAccessSourceSchema,
+});
+export const accountAccessVerdictSchema = z
+    .object({
+    accountId: z.string().min(1),
+    /** `null` when no such account exists. */
+    kind: accountKindSchema.nullable(),
+    /** `null` means: this person may not act for this account. */
+    access: accountAccessGrantSchema.nullable(),
+})
+    .refine((verdict) => verdict.access === null || verdict.kind !== null, {
+    message: 'An account that does not exist grants no access',
+    path: ['access'],
+});

package/dist/esm/agency.js

@@ -140,6 +140,35 @@ export const delegationGrantSchema = z
     updatedAt: z.string().datetime(),
 })
     .strict();
+/**
+ * The two levels an owner publishes for whoever uses their agent (ADR 0042):
+ * "Ver" and "Ver y actuar". A ceiling never says `draft` or `execute_on_request`:
+ * an agent is either allowed to act on its own or not at all, and nothing ever
+ * asks the person for approval.
+ */
+export const AGENT_REQUESTER_CEILING_AUTONOMY = ['read_only', 'autonomous'];
+/** What an agent may do in one app for whoever uses it; written by an operator of the bot. */
+export const agentRequesterCeilingWriteSchema = z
+    .object({
+    capabilityPackages: z.array(capabilityPackageSchema),
+    capabilities: z.array(identifierSchema).default([]),
+    toolOverrides: z.array(toolGrantOverrideSchema).default([]),
+    limits: z.array(grantLimitSchema).default([]),
+    maximumAutonomy: z.enum(AGENT_REQUESTER_CEILING_AUTONOMY),
+})
+    .strict();
+export const agentRequesterCeilingSchema = agentRequesterCeilingWriteSchema
+    .extend({
+    id: identifierSchema,
+    agentAccountId: identifierSchema,
+    appId: identifierSchema,
+    catalog: capabilityCatalogBindingSchema,
+    version: z.number().int().positive(),
+    revokedAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .strict();
 export const automationTriggerSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('manual') }).strict(),
     z
@@ -201,6 +230,8 @@ export const capabilityTicketClaimsSchema = z
     /** Signed only for callers that explicitly requested a pinned catalogue. */
     catalog: capabilityCatalogBindingSchema.optional(),
     grantId: identifierSchema.optional(),
+    /** The owner's published ceiling that bounds an agent acting for a non-owner (ADR 0042). */
+    ceilingId: identifierSchema.optional(),
     requesterAccountId: identifierSchema,
     ownerAccountId: identifierSchema,
     actor: executionActorRefSchema,
@@ -239,6 +270,24 @@ export const capabilityTicketClaimsSchema = z
             message: 'requester actors require their exact principal and direct read-only authority without standing grants',
         });
     }
+    if (claims.ceilingId !== undefined) {
+        if (claims.grantId !== undefined) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['ceilingId'],
+                message: 'a ticket is bounded by either a grant or a ceiling, never both',
+            });
+        }
+        if (claims.actor.type !== 'agent' ||
+            claims.ownerAccountId !== claims.requesterAccountId ||
+            claims.resource.resourceId !== claims.resource.effectiveAccountId) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['ceilingId'],
+                message: "a ceiling bounds an agent acting on the requester's own authority at an account root",
+            });
+        }
+    }
     if (claims.exp <= claims.iat) {
         context.addIssue({
             code: z.ZodIssueCode.custom,
@@ -300,6 +349,7 @@ export const policyDecisionSchema = z
     reason: identifierSchema,
     effectiveAutonomy: autonomyLevelSchema.optional(),
     grantId: identifierSchema.optional(),
+    ceilingId: identifierSchema.optional(),
 })
     .strict();
 export const auditResultSchema = z
@@ -509,6 +559,24 @@ export const catalogEventSchema = z
     resourceTypes: z.array(identifierSchema).min(1),
 })
     .strict();
+/**
+ * A feature an agent may gate on (Alia ADR 0020 §6): the app answers whether the
+ * person may use it (`checkTool`) and, when using it costs something, spends it
+ * (`consumeTool`). Both are internal tools of the same catalogue.
+ */
+export const catalogFeatureSchema = z
+    .object({
+    key: z
+        .string()
+        .regex(/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/, 'feature keys are dot-separated slugs')
+        .max(128),
+    description: nonEmptyStringSchema,
+    checkTool: identifierSchema,
+    consumeTool: identifierSchema.optional(),
+})
+    .strict();
+/** How a coordinator reaches the catalogue's internal tools. */
+export const CATALOG_INTERNAL_TRANSPORTS = ['http', 'mcp'];
 export const appCapabilityCatalogSchema = z
     .object({
     schemaVersion: z.literal('1'),
@@ -564,11 +632,54 @@ export const appCapabilityCatalogSchema = z
     })
         .strict()
         .optional(),
+    /**
+     * `mcp`: internal tools are served at `<internalBaseUrl>/_oxy/mcp`. Absent or
+     * `http`: each tool's `invocation` path on `internalBaseUrl`.
+     */
+    internalTransport: z.enum(CATALOG_INTERNAL_TRANSPORTS).optional(),
+    features: z.array(catalogFeatureSchema).optional(),
     tools: z.array(catalogToolSchema),
     events: z.array(catalogEventSchema),
 })
     .strict()
     .superRefine((catalog, context) => {
+    const toolsByName = new Map(catalog.tools.map((tool) => [tool.name, tool]));
+    const featureKeys = new Set();
+    for (const [index, feature] of (catalog.features ?? []).entries()) {
+        if (featureKeys.has(feature.key)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Duplicate feature key: ${feature.key}`,
+                path: ['features', index, 'key'],
+            });
+        }
+        featureKeys.add(feature.key);
+        const check = toolsByName.get(feature.checkTool);
+        if (!check ||
+            check.effect !== 'read' ||
+            check.exposure.length !== 1 ||
+            check.exposure[0] !== 'internal') {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'checkTool must name an internal-only read tool of this catalogue',
+                path: ['features', index, 'checkTool'],
+            });
+        }
+        if (feature.consumeTool !== undefined) {
+            const consume = toolsByName.get(feature.consumeTool);
+            if (!consume ||
+                consume.effect === 'read' ||
+                consume.idempotency !== 'required' ||
+                consume.exposure.length !== 1 ||
+                consume.exposure[0] !== 'internal') {
+                context.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: 'consumeTool must name an internal-only effectful tool that requires idempotency keys',
+                    path: ['features', index, 'consumeTool'],
+                });
+            }
+        }
+    }
     const names = new Set();
     for (const [index, tool] of catalog.tools.entries()) {
         if (names.has(tool.name)) {