@abloatai/transaction 0.37.0

package/dist/auth/browserCredentialSafety.js

@@ -0,0 +1,29 @@
+import { AbloAuthenticationError } from '../errors.js';
+import { classifyCredentialKind } from './credentialKind.js';
+import { credentialToken, } from './credentialResult.js';
+export function assertBrowserSafety(input) {
+    if (!input.dangerouslyAllowBrowser &&
+        typeof window !== 'undefined' &&
+        typeof input.apiKey === 'string' &&
+        classifyCredentialKind(input.apiKey) === 'secret') {
+        throwBrowserSecretError();
+    }
+}
+export function protectBrowserCredentialProvider(provider, dangerouslyAllowBrowser) {
+    return async () => {
+        const result = await provider();
+        const token = credentialToken(result);
+        if (!dangerouslyAllowBrowser &&
+            typeof window !== 'undefined' &&
+            token !== null &&
+            classifyCredentialKind(token) === 'secret') {
+            throwBrowserSecretError();
+        }
+        return result;
+    };
+}
+function throwBrowserSecretError() {
+    throw new AbloAuthenticationError('A secret `sk_` credential reached the browser. Keep it server-side and ' +
+        'configure the browser with `authEndpoint` instead.', { code: 'browser_apikey_blocked' });
+}
+//# sourceMappingURL=browserCredentialSafety.js.map

package/dist/auth/browserCredentialSafety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserCredentialSafety.js","sourceRoot":"","sources":["../../src/auth/browserCredentialSafety.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EACL,eAAe,GAGhB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,UAAU,mBAAmB,CAAC,KAGnC;IACC,IACE,CAAC,KAAK,CAAC,uBAAuB;QAC9B,OAAO,MAAM,KAAK,WAAW;QAC7B,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAChC,sBAAsB,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,QAAQ,EACjD,CAAC;QACD,uBAAuB,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,QAA4B,EAC5B,uBAA4C;IAE5C,OAAO,KAAK,IAAuC,EAAE;QACnD,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACtC,IACE,CAAC,uBAAuB;YACxB,OAAO,MAAM,KAAK,WAAW;YAC7B,KAAK,KAAK,IAAI;YACd,sBAAsB,CAAC,KAAK,CAAC,KAAK,QAAQ,EAC1C,CAAC;YACD,uBAAuB,EAAE,CAAC;QAC5B,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,uBAAuB;IAC9B,MAAM,IAAI,uBAAuB,CAC/B,yEAAyE;QACvE,oDAAoD,EACtD,EAAE,IAAI,EAAE,wBAAwB,EAAE,CACnC,CAAC;AACJ,CAAC"}

package/dist/auth/capability.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Capability — the one definition of what a credential may do.
+ *
+ * A grant is declared once, in the vocabulary a developer writes:
+ *
+ *     can: { documents: ['read', 'update'] }
+ *
+ * Everything downstream derives from that declaration: the wire spelling
+ * (`documents.update`) stored on the key row, the typed `can` a schema narrows
+ * to its own models, the request body the mint route parses, the pattern the
+ * published contract advertises, and the scope block echoed back on the minted
+ * session.
+ *
+ * Before this module the same grant was spelled five times — a literal union in
+ * the resource types, a `z.array(z.string())` on the wire, a hand-rolled
+ * field-by-field parser in the mint route, an object literal in the response
+ * type, and a hand-written `model.verb` array at each caller that mints without
+ * the SDK. Nothing failed when they drifted; the drift surfaced as
+ * `capability_scope_denied` on a grant the caller believed it held.
+ *
+ * Two axes decide blast radius. VERBS come from `can`; ROWS come from
+ * `syncGroups`. They belong to one grant, which is why they are declared
+ * together here rather than meeting for the first time on the wire.
+ */
+import { z } from 'zod';
+/**
+ * The verbs a grant can name — the whole vocabulary, in one place. Every other
+ * spelling of an operation in the system derives from this enum: the SDK's
+ * `can` values, the wire's `model.verb` pattern, and the JSON Schema the
+ * published contract advertises.
+ */
+export declare const capabilityOperationSchema: z.ZodEnum<{
+    update: "update";
+    create: "create";
+    delete: "delete";
+    read: "read";
+}>;
+export type CapabilityOperation = z.infer<typeof capabilityOperationSchema>;
+/**
+ * One granted operation in its wire spelling: `<model>.<verb>`, lowercased.
+ *
+ * The template literal derives both halves — the verb set from
+ * {@link capabilityOperationSchema}, the pattern in the published contract from
+ * the template — so tightening the verb vocabulary can never leave a stale
+ * regex or a stale doc behind. The model half is the name the server matches
+ * against a model's registered aliases (type name, schema key, or table name),
+ * so it stays permissive here and is resolved at the gate.
+ */
+export declare const grantedOperationSchema: z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>;
+export type GrantedOperation = z.infer<typeof grantedOperationSchema>;
+/**
+ * The declared grant, per model — the runtime shape of `can`. Model keys are
+ * free-form at runtime because the server resolves them against the schema it
+ * has; {@link CapabilityCan} narrows them to a known schema's models at the
+ * type level.
+ */
+export declare const capabilityCanSchema: z.ZodRecord<z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+    update: "update";
+    create: "create";
+    delete: "delete";
+    read: "read";
+}>>>>;
+export type NonEmptyCapabilityOperations = readonly [
+    CapabilityOperation,
+    ...CapabilityOperation[]
+];
+/**
+ * `can`, narrowed to one schema's model names. A projection of
+ * {@link capabilityCanSchema} — the value type is the operation enum, the key
+ * domain is the schema's models, so `can: { tasks: ['update'] }` fails to
+ * compile against a schema with no `tasks` model.
+ */
+export type CapabilityCan<S> = {
+    [K in keyof S & string]: Readonly<Record<K, NonEmptyCapabilityOperations>> & Partial<Record<Exclude<keyof S & string, K>, NonEmptyCapabilityOperations>>;
+}[keyof S & string];
+/**
+ * Public authoring type for a reusable grant. It accepts the `Schema` itself,
+ * so callers can use TypeScript's `satisfies` operator without reaching into
+ * `schema.models`.
+ */
+export type CapabilityGrant<S extends {
+    readonly models: Readonly<Record<string, unknown>>;
+}> = CapabilityCan<S['models']>;
+/**
+ * Bind the canonical `can` Zod contract to one schema's model keys.
+ *
+ * The wire parser cannot know a tenant's models until a schema is selected.
+ * This projection keeps the same operation/value contract and rejects keys
+ * outside that selected schema.
+ */
+export declare function capabilityCanSchemaFor<const S extends Readonly<Record<string, unknown>>>(models: S): z.ZodRecord<z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+    update: "update";
+    create: "create";
+    delete: "delete";
+    read: "read";
+}>>>>;
+/**
+ * Read-your-writes expansion: append `<model>.read` for every model the grant
+ * can write.
+ *
+ * A scoped agent that may update a row must be able to read it, or the read
+ * gate (query / bootstrap / entity self-heal / delta fan-out) starves the very
+ * writes the grant allows. The write verbs stay the source of truth; reads are
+ * derived and deduped, and models the grant cannot write stay unreadable —
+ * that is the read-side blast-radius reduction.
+ *
+ * It lives beside the declaration, so it applies wherever a grant is built,
+ * rather than only at whichever mint the callers happen to share. The server
+ * applies it again at the mint chokepoint for callers that post raw JSON; the
+ * function is idempotent, so the second application is a no-op.
+ */
+export declare function expandReadYourWrites(operations: readonly GrantedOperation[]): GrantedOperation[];
+/**
+ * The parts of a model definition a grant can name. Structural, so both the
+ * SDK (which holds a `Schema`) and the mint route (which holds the tenant's
+ * pushed artifact) derive names from the same rule.
+ */
+export interface CapabilityModelShape {
+    readonly typename?: string;
+    readonly tableName?: string;
+}
+/**
+ * Schema key → the wire name a grant must be minted with.
+ *
+ * THE derivation. A model whose type name is overridden — schema key
+ * `documents`, type name `Document` — has to mint `document.update`, not
+ * `documents.update`, and a caller who works that out by hand gets it wrong
+ * once and learns at `capability_scope_denied`. Callers pass their schema's
+ * models, never a map they assembled themselves.
+ */
+export declare function modelWireNames(models: Readonly<Record<string, CapabilityModelShape>>): Record<string, string>;
+/**
+ * Every name the enforcement gates accept for a model, lowercased. Three
+ * vocabularies name one logical model — the wire type name (`lineitem`), the
+ * schema key (`lineItems`), and the table name (`line_items`) — so a grant
+ * minted in any of them is honored, and the mint can tell a real model from a
+ * typo without guessing which vocabulary the caller used.
+ */
+export declare function capabilityModelAliases(models: Readonly<Record<string, CapabilityModelShape>>): Set<string>;
+/**
+ * The granted operations whose model half names nothing in the schema.
+ *
+ * A grant is checked against the schema at MINT, the way a write to an unpushed
+ * model already fails with `server_execute_unknown_model` — so a typo in
+ * `lineitem.update` is a rejected mint rather than a credential that looks
+ * healthy and is denied on its first write. Without this the `model` half is a
+ * hole: an opaque string nothing validates until enforcement time.
+ */
+export declare function unresolvableOperations(operations: readonly GrantedOperation[], aliases: ReadonlySet<string>): GrantedOperation[];
+/**
+ * Serializes a declared `can` into the wire allowlist — the ONE translation
+ * from what a developer writes to what the server stores and enforces.
+ *
+ * `wireNames` comes from {@link modelWireNames} over the client's own schema.
+ * It is required rather than optional: an omitted map silently mints the schema
+ * key verbatim, which is right for most models and wrong for every model with
+ * a type-name override — the kind of default that is correct until it isn't.
+ */
+export declare function grantedOperations(can: Readonly<Record<string, readonly CapabilityOperation[] | undefined>>, wireNames: Readonly<Record<string, string>>): GrantedOperation[];
+/**
+ * The grant at rest: what the credential ended up with, on both axes, plus the
+ * participant it acts as. The mint echoes this block, the key row stores it,
+ * and the gates read it — so a session's reported scope and its enforced scope
+ * are the same shape by construction.
+ */
+export declare const capabilityScopeSchema: z.ZodObject<{
+    organizationId: z.ZodString;
+    syncGroups: z.ZodArray<z.ZodString>;
+    operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
+    participantKind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    participantId: z.ZodString;
+}, z.core.$strip>;
+export type CapabilityScope = z.infer<typeof capabilityScopeSchema>;
+/**
+ * What `POST /v1/capabilities` answers with — **201**, the credential is minted.
+ *
+ * This is the first call any non-TypeScript client makes, and until it had a
+ * schema the published contract described it as `{ type: 'object' }`: a caller
+ * working from the reference could see that a capability could be minted and
+ * not where the token was in the reply.
+ *
+ * `scope` echoes what was MINTED, not what was asked. A `wideScope` mint stores
+ * the org-wide default and read-your-writes widens the verb axis, so a client
+ * that assumed its request came back verbatim would report a scope narrower
+ * than the one being enforced.
+ *
+ * `userMeta` is the caller's own blob, echoed. Ablo has no view into their user
+ * directory — the API key is what is trusted — so this is deliberately open.
+ */
+export declare const capabilityMintResponseSchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    organizationId: z.ZodString;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        syncGroups: z.ZodArray<z.ZodString>;
+        operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
+        participantKind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        participantId: z.ZodString;
+    }, z.core.$strip>;
+    userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type CapabilityMintResponse = z.infer<typeof capabilityMintResponseSchema>;
+/**
+ * `POST /v1/capabilities` — mint a capability for a participant.
+ *
+ * Where an ephemeral key is a session for a person, a capability is a scoped,
+ * revocable grant for an agent or a system. Narrow by default: an agent or
+ * system capability must name its `operations` unless the caller explicitly
+ * asks for `wideScope`, which is itself privileged.
+ *
+ * This is the parsed body — the mint route validates against it rather than
+ * reading fields one at a time, so the shape and the validation rules cannot
+ * drift from each other or from the published contract.
+ */
+export declare const capabilityRequestSchema: z.ZodObject<{
+    participantKind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    participantId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    syncGroups: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>>>>;
+    operations: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>>>;
+    ttlSeconds: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+    wideScope: z.ZodOptional<z.ZodBoolean>;
+    userMeta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type CapabilityRequest = z.infer<typeof capabilityRequestSchema>;
+//# sourceMappingURL=capability.d.ts.map

package/dist/auth/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/auth/capability.ts"],"names":[],"mappings":"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"}

package/dist/auth/capability.js

@@ -0,0 +1,253 @@
+/**
+ * Capability — the one definition of what a credential may do.
+ *
+ * A grant is declared once, in the vocabulary a developer writes:
+ *
+ *     can: { documents: ['read', 'update'] }
+ *
+ * Everything downstream derives from that declaration: the wire spelling
+ * (`documents.update`) stored on the key row, the typed `can` a schema narrows
+ * to its own models, the request body the mint route parses, the pattern the
+ * published contract advertises, and the scope block echoed back on the minted
+ * session.
+ *
+ * Before this module the same grant was spelled five times — a literal union in
+ * the resource types, a `z.array(z.string())` on the wire, a hand-rolled
+ * field-by-field parser in the mint route, an object literal in the response
+ * type, and a hand-written `model.verb` array at each caller that mints without
+ * the SDK. Nothing failed when they drifted; the drift surfaced as
+ * `capability_scope_denied` on a grant the caller believed it held.
+ *
+ * Two axes decide blast radius. VERBS come from `can`; ROWS come from
+ * `syncGroups`. They belong to one grant, which is why they are declared
+ * together here rather than meeting for the first time on the wire.
+ */
+import { z } from 'zod';
+import { participantKindSchema } from '../coordination/schema.js';
+import { syncGroupInputSchema } from '../schema/roles.js';
+import { authTokenSchema } from './token.js';
+/**
+ * The verbs a grant can name — the whole vocabulary, in one place. Every other
+ * spelling of an operation in the system derives from this enum: the SDK's
+ * `can` values, the wire's `model.verb` pattern, and the JSON Schema the
+ * published contract advertises.
+ */
+export const capabilityOperationSchema = z.enum(['read', 'create', 'update', 'delete']);
+/**
+ * One granted operation in its wire spelling: `<model>.<verb>`, lowercased.
+ *
+ * The template literal derives both halves — the verb set from
+ * {@link capabilityOperationSchema}, the pattern in the published contract from
+ * the template — so tightening the verb vocabulary can never leave a stale
+ * regex or a stale doc behind. The model half is the name the server matches
+ * against a model's registered aliases (type name, schema key, or table name),
+ * so it stays permissive here and is resolved at the gate.
+ */
+export const grantedOperationSchema = z.templateLiteral([
+    z.string().regex(/^[^.\s]+$/),
+    '.',
+    capabilityOperationSchema,
+]);
+/**
+ * The declared grant, per model — the runtime shape of `can`. Model keys are
+ * free-form at runtime because the server resolves them against the schema it
+ * has; {@link CapabilityCan} narrows them to a known schema's models at the
+ * type level.
+ */
+export const capabilityCanSchema = z.record(z.string().min(1), z.array(capabilityOperationSchema).min(1).readonly()).refine((can) => Object.keys(can).length > 0, {
+    message: 'can must grant at least one operation',
+});
+/**
+ * Bind the canonical `can` Zod contract to one schema's model keys.
+ *
+ * The wire parser cannot know a tenant's models until a schema is selected.
+ * This projection keeps the same operation/value contract and rejects keys
+ * outside that selected schema.
+ */
+export function capabilityCanSchemaFor(models) {
+    const modelNames = new Set(Object.keys(models));
+    return capabilityCanSchema.superRefine((can, ctx) => {
+        for (const model of Object.keys(can)) {
+            if (!modelNames.has(model)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: [model],
+                    message: `Model "${model}" is not declared by this schema.`,
+                });
+            }
+        }
+    });
+}
+/**
+ * Read-your-writes expansion: append `<model>.read` for every model the grant
+ * can write.
+ *
+ * A scoped agent that may update a row must be able to read it, or the read
+ * gate (query / bootstrap / entity self-heal / delta fan-out) starves the very
+ * writes the grant allows. The write verbs stay the source of truth; reads are
+ * derived and deduped, and models the grant cannot write stay unreadable —
+ * that is the read-side blast-radius reduction.
+ *
+ * It lives beside the declaration, so it applies wherever a grant is built,
+ * rather than only at whichever mint the callers happen to share. The server
+ * applies it again at the mint chokepoint for callers that post raw JSON; the
+ * function is idempotent, so the second application is a no-op.
+ */
+export function expandReadYourWrites(operations) {
+    const out = new Set(operations);
+    for (const op of operations) {
+        const [model] = op.split('.');
+        if (model)
+            out.add(`${model}.read`);
+    }
+    return [...out];
+}
+/**
+ * Schema key → the wire name a grant must be minted with.
+ *
+ * THE derivation. A model whose type name is overridden — schema key
+ * `documents`, type name `Document` — has to mint `document.update`, not
+ * `documents.update`, and a caller who works that out by hand gets it wrong
+ * once and learns at `capability_scope_denied`. Callers pass their schema's
+ * models, never a map they assembled themselves.
+ */
+export function modelWireNames(models) {
+    return Object.fromEntries(Object.entries(models).map(([key, def]) => [key, def.typename ?? key]));
+}
+/**
+ * Every name the enforcement gates accept for a model, lowercased. Three
+ * vocabularies name one logical model — the wire type name (`lineitem`), the
+ * schema key (`lineItems`), and the table name (`line_items`) — so a grant
+ * minted in any of them is honored, and the mint can tell a real model from a
+ * typo without guessing which vocabulary the caller used.
+ */
+export function capabilityModelAliases(models) {
+    const aliases = new Set();
+    for (const [key, def] of Object.entries(models)) {
+        aliases.add(key.toLowerCase());
+        if (def.typename)
+            aliases.add(def.typename.toLowerCase());
+        if (def.tableName)
+            aliases.add(def.tableName.toLowerCase());
+    }
+    return aliases;
+}
+/**
+ * The granted operations whose model half names nothing in the schema.
+ *
+ * A grant is checked against the schema at MINT, the way a write to an unpushed
+ * model already fails with `server_execute_unknown_model` — so a typo in
+ * `lineitem.update` is a rejected mint rather than a credential that looks
+ * healthy and is denied on its first write. Without this the `model` half is a
+ * hole: an opaque string nothing validates until enforcement time.
+ */
+export function unresolvableOperations(operations, aliases) {
+    // The model half holds no dot (see `grantedOperationSchema`), so the first
+    // separator is the only one.
+    return operations.filter((op) => !aliases.has(op.slice(0, op.indexOf('.'))));
+}
+/**
+ * Serializes a declared `can` into the wire allowlist — the ONE translation
+ * from what a developer writes to what the server stores and enforces.
+ *
+ * `wireNames` comes from {@link modelWireNames} over the client's own schema.
+ * It is required rather than optional: an omitted map silently mints the schema
+ * key verbatim, which is right for most models and wrong for every model with
+ * a type-name override — the kind of default that is correct until it isn't.
+ */
+export function grantedOperations(can, wireNames) {
+    const declared = Object.entries(can).flatMap(([model, ops]) => {
+        const wireName = (wireNames[model] ?? model).toLowerCase();
+        return (ops ?? []).map((op) => `${wireName}.${op}`);
+    });
+    return expandReadYourWrites(declared);
+}
+/**
+ * The grant at rest: what the credential ended up with, on both axes, plus the
+ * participant it acts as. The mint echoes this block, the key row stores it,
+ * and the gates read it — so a session's reported scope and its enforced scope
+ * are the same shape by construction.
+ */
+export const capabilityScopeSchema = z.object({
+    organizationId: z.string().min(1),
+    /**
+     * The ROW axis — which sync groups this credential may act within. Read back
+     * as plain strings rather than the branded form the request enforces: this is
+     * what the key row already holds, including rows minted before that gate.
+     */
+    syncGroups: z.array(z.string()),
+    /** The VERB axis — the allowlist as minted, after read-your-writes. */
+    operations: z.array(grantedOperationSchema),
+    participantKind: participantKindSchema,
+    participantId: z.string().min(1),
+});
+/**
+ * What `POST /v1/capabilities` answers with — **201**, the credential is minted.
+ *
+ * This is the first call any non-TypeScript client makes, and until it had a
+ * schema the published contract described it as `{ type: 'object' }`: a caller
+ * working from the reference could see that a capability could be minted and
+ * not where the token was in the reply.
+ *
+ * `scope` echoes what was MINTED, not what was asked. A `wideScope` mint stores
+ * the org-wide default and read-your-writes widens the verb axis, so a client
+ * that assumed its request came back verbatim would report a scope narrower
+ * than the one being enforced.
+ *
+ * `userMeta` is the caller's own blob, echoed. Ablo has no view into their user
+ * directory — the API key is what is trusted — so this is deliberately open.
+ */
+export const capabilityMintResponseSchema = z.object({
+    capabilityId: z.string().min(1),
+    token: authTokenSchema,
+    expiresAt: z.iso.datetime(),
+    organizationId: z.string().min(1),
+    scope: capabilityScopeSchema,
+    userMeta: z.record(z.string(), z.unknown()),
+});
+/**
+ * `POST /v1/capabilities` — mint a capability for a participant.
+ *
+ * Where an ephemeral key is a session for a person, a capability is a scoped,
+ * revocable grant for an agent or a system. Narrow by default: an agent or
+ * system capability must name its `operations` unless the caller explicitly
+ * asks for `wideScope`, which is itself privileged.
+ *
+ * This is the parsed body — the mint route validates against it rather than
+ * reading fields one at a time, so the shape and the validation rules cannot
+ * drift from each other or from the published contract.
+ */
+export const capabilityRequestSchema = z.object({
+    participantKind: participantKindSchema,
+    participantId: z.string().min(1).optional(),
+    /**
+     * Mint into another organization. Reserved for a platform secret carrying
+     * `ephemeral:mint-any-org`; ordinary tenant keys may omit only.
+     */
+    organizationId: z.string().min(1).optional(),
+    /**
+     * The ROW axis. Validated as the engine's branded sync-group form
+     * (`default` or `<namespace>:<id>`): a malformed group stored on the key row
+     * would subscribe the connection to NOTHING and fail silently at fan-out
+     * time, so it is rejected loudly at the boundary.
+     */
+    syncGroups: z.array(syncGroupInputSchema).readonly().optional(),
+    /** The VERB axis, as `model.verb` — e.g. `tasks.update`. */
+    operations: z.array(grantedOperationSchema).readonly().optional(),
+    ttlSeconds: z.number().int().positive(),
+    label: z.string().min(1).optional(),
+    /**
+     * Opt out of narrow-by-default scoping. Without it, agent and system
+     * capabilities require non-empty `operations`; with it, the caller must
+     * additionally hold an admin/owner role or present a secret key.
+     */
+    wideScope: z.boolean().optional(),
+    /**
+     * Caller-attested identity for the end user this capability acts for — the
+     * on-behalf-of pattern. Ablo does not validate it and has no view into the
+     * caller's user directory; the API key is what is trusted, and this blob is
+     * echoed back to the client.
+     */
+    userMeta: z.record(z.string(), z.unknown()).optional(),
+});
+//# sourceMappingURL=capability.js.map

package/dist/auth/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/auth/capability.ts"],"names":[],"mappings":"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"}

package/dist/auth/capabilityLifecycle.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { RotateSessionParams, SessionRevocation, SessionRotation } from '../resources/httpResources.js';
+export declare const sessionRevocationResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    deleted: z.ZodLiteral<true>;
+    activeSessionsClosed: z.ZodNumber;
+}, z.core.$strip>;
+export declare const capabilityRotationRequestSchema: z.ZodObject<{
+    graceSeconds: z.ZodOptional<z.ZodNumber>;
+    ttlSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const capabilityRotationResponseSchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodNullable<z.ZodISODateTime>;
+    organizationId: z.ZodString;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        syncGroups: z.ZodArray<z.ZodString>;
+        operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
+        participantKind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        participantId: z.ZodString;
+    }, z.core.$strip>;
+    rotatedFrom: z.ZodObject<{
+        capabilityId: z.ZodString;
+        expiresAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+interface CapabilityLifecycleContext {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export interface RevokeCapabilityRequest extends CapabilityLifecycleContext {
+    readonly id: string;
+}
+export interface RotateCapabilityRequest extends CapabilityLifecycleContext, RotateSessionParams {
+}
+export declare function revokeCapability(options: RevokeCapabilityRequest): Promise<SessionRevocation>;
+export declare function rotateCapability(options: RotateCapabilityRequest): Promise<SessionRotation>;
+export {};
+//# sourceMappingURL=capabilityLifecycle.d.ts.map

package/dist/auth/capabilityLifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityLifecycle.d.ts","sourceRoot":"","sources":["../../src/auth/capabilityLifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EAChB,MAAM,+BAA+B,CAAC;AAEvC,eAAO,MAAM,+BAA+B;;;;iBAI1C,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;iBAG1C,CAAC;AAEH,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;iBAU3C,CAAC;AAEH,UAAU,0BAA0B;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAwB,SAAQ,0BAA0B;IACzE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBACf,SAAQ,0BAA0B,EAChC,mBAAmB;CAAG;AAwE1B,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,eAAe,CAAC,CAiC1B"}