@absolutejs/secrets 0.5.3 → 0.6.0

package/README.md

@@ -17,6 +17,56 @@ SB-6 substrate are `@absolutejs/sync`'s `bridgeFetch.authorization()` hook
 declarations (per-customer host functions like Stripe charge, Slack ping,
 queue push).
 
+## Agent credential operations
+
+Agents should not call `resolve()` and should never receive a bearer token.
+`createCredentialOperationBroker()` instead gives them bounded capabilities:
+an exact agent and user, provider, operation scopes, URL origins, expiry, and
+maximum use count. The host resolves the secret only after the grant is
+atomically consumed, then passes it directly to an allowlisted provider
+operation. Results and audit events contain digests and identifiers, never the
+credential.
+
+```ts
+const grants = createMemoryCredentialGrantStore();
+await grants.put({
+  agentId: 'research-agent',
+  allowedOrigins: ['https://api.example.com'],
+  createdAt: Date.now(),
+  expiresAt: Date.now() + 60_000,
+  grantId: 'grant_123',
+  maximumUses: 1,
+  provider: 'example',
+  scopes: ['create-report'],
+  secretName: 'EXAMPLE_API_KEY',
+  used: 0,
+  userId: 'user_123',
+});
+
+const operations = createCredentialOperationBroker({
+  agency,
+  providers: [{
+    provider: 'example',
+    operations: {
+      'create-report': ({ credential, destination, input, signal }) =>
+        fetch(new URL('/reports', destination), {
+          body: JSON.stringify(input),
+          headers: { authorization: `Bearer ${credential}` },
+          method: 'POST',
+          signal,
+        }).then((response) => response.json()),
+    },
+  }],
+  secrets: broker,
+  store: grants,
+});
+```
+
+Use a durable `CredentialGrantStore` in production. Passing an `agency` adds
+policy, approval, single-use execution lease, and receipt enforcement.
+Requestable denials can be resumed after approval with
+`operations.resume(actionId)`.
+
 ```ts
 import { createSecretBroker, envAdapter, inMemoryAdapter, compositeAdapter } from '@absolutejs/secrets';
 

package/dist/index.d.ts

@@ -24,6 +24,7 @@
  * The broker is bun/elysia-agnostic — same posture as router + meter.
  */
 import { type TracerProvider } from '@absolutejs/telemetry';
+export { createCredentialOperationBroker, createMemoryCredentialGrantStore, type CredentialGrant, type CredentialGrantStore, type CredentialOperationBroker, type CredentialOperationBrokerOptions, type CredentialOperationContext, type CredentialOperationEvent, type CredentialOperationInput, type CredentialOperationResult, type CredentialProvider, type PendingCredentialOperation } from './operations';
 export type SecretValue = {
     /** The plaintext secret. Treat as poison: never log, never serialize. */
     value: string;

package/dist/index.js

@@ -68,6 +68,193 @@ var ABS_ATTRS = {
   auditKind: "abs.audit.kind"
 };
 
+// node_modules/@absolutejs/agency/dist/index.js
+var normalize = (value) => {
+  if (Array.isArray(value))
+    return value.map(normalize);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, normalize(entry)]));
+  }
+  return value;
+};
+var canonicalJson = (value) => JSON.stringify(normalize(value));
+var digest = async (value) => {
+  const encoded = new TextEncoder().encode(canonicalJson(value));
+  const result = await crypto.subtle.digest("SHA-256", encoded);
+  return [...new Uint8Array(result)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+
+// src/operations.ts
+var normalizeOrigin = (destination) => new URL(destination).origin;
+var validateGrant = (grant, input, now) => {
+  if (grant.agentId !== input.actor.agentId || grant.userId !== input.actor.userId)
+    throw new Error("Credential grant actor mismatch");
+  if (grant.expiresAt <= now)
+    throw new Error("Credential grant has expired");
+  if (!grant.scopes.includes(input.operation))
+    throw new Error("Credential operation is outside grant scope");
+  const origin = normalizeOrigin(input.destination);
+  if (!grant.allowedOrigins.map(normalizeOrigin).includes(origin))
+    throw new Error("Credential destination is outside grant scope");
+  if (grant.used >= grant.maximumUses)
+    throw new Error("Credential grant has been exhausted");
+  return origin;
+};
+var createMemoryCredentialGrantStore = () => {
+  const grants = new Map;
+  const pending = new Map;
+  let lock = Promise.resolve();
+  const exclusive = async (run) => {
+    const previous = lock;
+    let release = () => {};
+    lock = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      return await run();
+    } finally {
+      release();
+    }
+  };
+  return {
+    consume: (grantId, now) => exclusive(() => {
+      const grant = grants.get(grantId);
+      if (grant === undefined || grant.expiresAt <= now || grant.used >= grant.maximumUses)
+        return;
+      const consumed = { ...grant, used: grant.used + 1 };
+      grants.set(grantId, consumed);
+      return { ...consumed };
+    }),
+    get: async (grantId) => {
+      const grant = grants.get(grantId);
+      return grant === undefined ? undefined : { ...grant };
+    },
+    getPending: async (actionId) => pending.get(actionId),
+    put: async (grant) => {
+      if (grant.maximumUses < 1)
+        throw new Error("maximumUses must be positive");
+      if (grant.used < 0 || grant.used > grant.maximumUses)
+        throw new Error("Invalid credential grant usage");
+      grants.set(grant.grantId, { ...grant });
+    },
+    putPending: async (operation) => {
+      pending.set(operation.actionId, operation);
+    },
+    revoke: async (grantId) => grants.delete(grantId)
+  };
+};
+var createCredentialOperationBroker = ({
+  agency,
+  emit,
+  now = Date.now,
+  providers,
+  secrets,
+  store
+}) => {
+  const providerMap = new Map(providers.map((provider) => [provider.provider, provider]));
+  const perform = async (input, actionId, signal) => {
+    const preview = await store.get(input.grantId);
+    if (preview === undefined)
+      throw new Error("Unknown credential grant");
+    const origin = validateGrant(preview, input, now());
+    const provider = providerMap.get(preview.provider);
+    const operation = provider?.operations[input.operation];
+    if (provider === undefined || operation === undefined)
+      throw new Error("Credential provider operation is not registered");
+    await emit?.({
+      actionId,
+      destinationOrigin: origin,
+      grantId: preview.grantId,
+      operation: input.operation,
+      provider: preview.provider,
+      type: "credential.operation.requested"
+    });
+    const consumed = await store.consume(input.grantId, now());
+    if (consumed === undefined)
+      throw new Error("Credential grant has been exhausted");
+    validateGrant({ ...consumed, used: consumed.used - 1 }, input, now());
+    const secret = await secrets.resolve(consumed.secretName);
+    if (secret === null)
+      throw new Error("Credential is not configured");
+    try {
+      const result = await operation({
+        credential: secret.value,
+        destination: new URL(input.destination),
+        input: input.input,
+        signal
+      });
+      const resultDigest = await digest(result);
+      await emit?.({
+        actionId,
+        destinationOrigin: origin,
+        grantId: consumed.grantId,
+        operation: input.operation,
+        provider: consumed.provider,
+        resultDigest,
+        status: "succeeded",
+        type: "credential.operation.completed"
+      });
+      return { actionId, kind: "completed", result, resultDigest };
+    } catch (error) {
+      await emit?.({
+        actionId,
+        destinationOrigin: origin,
+        grantId: consumed.grantId,
+        operation: input.operation,
+        provider: consumed.provider,
+        status: "failed",
+        type: "credential.operation.completed"
+      });
+      throw error;
+    }
+  };
+  const request = async (input, signal) => {
+    const grant = await store.get(input.grantId);
+    if (grant === undefined)
+      throw new Error("Unknown credential grant");
+    const origin = validateGrant(grant, input, now());
+    if (agency === undefined)
+      return perform(input, undefined, signal);
+    const { action, decision } = await agency.request({
+      action: `credential.${grant.provider}.${input.operation}`,
+      actor: input.actor,
+      context: { destinationOrigin: origin, grantId: grant.grantId },
+      effects: ["external-network"],
+      expiresAt: grant.expiresAt,
+      idempotencyKey: input.idempotencyKey,
+      input: { destination: input.destination, input: input.input },
+      resource: { id: grant.grantId, type: "credential-grant" }
+    });
+    if (decision.kind !== "allow") {
+      await store.putPending({ actionId: action.actionId, input });
+      return { actionId: action.actionId, decision, kind: "pending" };
+    }
+    const lease = await agency.issueLease(action.actionId);
+    const execution = await agency.execute({
+      executor: `credential-provider:${grant.provider}`,
+      leaseId: lease.leaseId,
+      run: () => perform(input, action.actionId, signal)
+    });
+    return execution.result;
+  };
+  const resume = async (actionId, signal) => {
+    if (agency === undefined)
+      throw new Error("Agency is not configured");
+    const pending = await store.getPending(actionId);
+    if (pending === undefined)
+      throw new Error("Unknown pending credential operation");
+    const lease = await agency.issueLease(actionId);
+    const execution = await agency.execute({
+      executor: "credential-provider",
+      leaseId: lease.leaseId,
+      run: () => perform(pending.input, actionId, signal)
+    });
+    return execution.result;
+  };
+  return { request, resume, revoke: store.revoke };
+};
+
 // src/index.ts
 class BrokerDrainedError extends Error {
   constructor() {
@@ -802,9 +989,11 @@ export {
   envAdapter,
   encryptedFileAdapter,
   createSecretBroker,
+  createMemoryCredentialGrantStore,
+  createCredentialOperationBroker,
   compositeAdapter,
   BrokerDrainedError
 };
 
-//# debugId=51F9793EA6C3ED2F64756E2164756E21
+//# debugId=733FE5935B42EE2D64756E2164756E21
 //# sourceMappingURL=index.js.map