@emilia-protocol/gate 0.9.5 → 0.11.0

package/adapters/_kit.js

@@ -6,15 +6,29 @@
  * gate.run(), and FAIL CLOSED — if the gate refuses, the real client call is
  * never made and we throw EMILIA_RECEIPT_REQUIRED.
  *
- * An op spec is: { selector, observed(params) -> {fields...}, perform(client, params) -> result }.
+ * An op spec is: { selector, observed(params) -> {fields...},
+ * actuator?(params, observed) -> {fields...}, perform(client, actuator) -> result }.
  * `observed` must return the same material fields the action pack binds, drawn
  * from the call params (the system-of-record facts), so a receipt for resource A
  * cannot authorize a mutation of resource B.
  */
-import { hashCanonical } from '../execution-binding.js';
+import { canonicalize, hashCanonical } from '../execution-binding.js';
 
 export { hashCanonical };
 
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** Canonical plain-data snapshot used at the actuator boundary. */
+export function canonicalActuatorObject(value) {
+  return deepFreeze(JSON.parse(canonicalize(value)));
+}
+
 /** Build an EP-ACTION-RISK-MANIFEST-v0.1 from a frozen action pack (deep-copied). */
 export function manifestFromPack(pack, extraActions = []) {
   return {
@@ -26,6 +40,9 @@ export function manifestFromPack(pack, extraActions = []) {
         execution_binding: a.execution_binding
           ? { ...a.execution_binding, required_fields: [...a.execution_binding.required_fields] }
           : undefined,
+        ...(a.business_authorization
+          ? { business_authorization: canonicalActuatorObject(a.business_authorization) }
+          : {}),
       })),
       ...extraActions,
     ],
@@ -44,8 +61,33 @@ export function createAdapter({ system, ops }) {
     if (!gate || typeof gate.run !== 'function') throw new Error(`${system} adapter requires an EMILIA Gate (with .run)`);
     const spec = ops[op];
     if (!spec) throw new Error(`${system} adapter: unknown op "${op}" (expected one of: ${OPS.join(', ')})`);
-    const observedAction = spec.observed(params);
-    const out = await gate.run({ selector: spec.selector, receipt, observedAction }, () => spec.perform(client, params));
+    if (!receipt) {
+      const refused = await gate.run(
+        { selector: spec.selector, receipt: null, observedAction: null },
+        () => { throw new Error('unreachable_adapter_effect'); },
+      );
+      const e = new Error(`EMILIA Gate refused ${system}:${op} — ${refused.authorization.reason}`);
+      e.code = 'EMILIA_RECEIPT_REQUIRED';
+      e.status = refused.status;
+      e.gate = refused.authorization;
+      e.challenge = refused.body;
+      throw e;
+    }
+    // Snapshot before any asynchronous verification. Caller-owned params may be
+    // mutated while gate.run() awaits evidence/storage; neither the observation
+    // nor the eventual provider call may follow that mutable reference.
+    const input = canonicalActuatorObject(params);
+    const observedAction = canonicalActuatorObject(spec.observed(input));
+    // Default to the verified fields only. Operations that need a preimage for a
+    // bound digest (SQL, RLS, secret values, queries) must opt in with an explicit
+    // actuator() constructor. The unrestricted caller object is never passed.
+    const actuator = canonicalActuatorObject(
+      typeof spec.actuator === 'function' ? spec.actuator(input, observedAction) : observedAction,
+    );
+    const out = await gate.run(
+      { selector: spec.selector, receipt, observedAction },
+      () => spec.perform(client, actuator),
+    );
     if (!out.ok) {
       const e = new Error(`EMILIA Gate refused ${system}:${op} — ${out.authorization.reason}`);
       e.code = 'EMILIA_RECEIPT_REQUIRED';
@@ -60,4 +102,4 @@ export function createAdapter({ system, ops }) {
   return { ops, OPS, guard };
 }
 
-export default { createAdapter, manifestFromPack, hashCanonical };
+export default { createAdapter, manifestFromPack, hashCanonical, canonicalActuatorObject };

package/adapters/aws.js

@@ -13,7 +13,7 @@
  *   import { createGate } from '@emilia-protocol/gate';
  *   import { createAwsManifest, guardAwsMutation } from '@emilia-protocol/gate/adapters/aws';
  *
- *   const gate = createGate({ manifest: createAwsManifest(), trustedKeys: [ISSUER] });
+ *   const gate = createGate({ manifest: createAwsManifest(), trustedKeys: [ISSUER], store: sharedConsumptionStore });
  *   // client: { iam: { attachUserPolicy, createAccessKey, deleteUser }, ec2: { authorizeSecurityGroupIngress } }
  *   await guardAwsMutation(gate, client, {
  *     op: 'iam.attach_policy', params: { user: 'svc-bot', policy_arn: 'arn:aws:iam::aws:policy/AdministratorAccess' }, receipt,
@@ -48,7 +48,7 @@ export const AWS_ACTION_PACK = Object.freeze([
     risk: 'critical', receipt_required: true, assurance_class: 'quorum',
     match: { protocol: 'aws', tool: 'authorize_security_group_ingress' },
     why: 'Opens the network. Bind group/CIDR/port so 0.0.0.0/0:22 cannot slip through.',
-    execution_binding: { required_fields: ['action_type', 'group_id', 'cidr', 'from_port'] },
+    execution_binding: { required_fields: ['action_type', 'group_id', 'cidr', 'protocol', 'from_port', 'to_port'] },
   }),
 ]);
 
@@ -70,9 +70,20 @@ const OPS = {
   },
   'ec2.authorize_ingress': {
     selector: { protocol: 'aws', tool: 'authorize_security_group_ingress' },
-    observed: (p) => ({ action_type: 'aws.ec2.authorize_ingress', group_id: p.group_id, cidr: p.cidr, from_port: p.from_port }),
+    observed: (p) => ({
+      action_type: 'aws.ec2.authorize_ingress',
+      group_id: p.group_id,
+      cidr: p.cidr,
+      protocol: p.protocol ?? 'tcp',
+      from_port: p.from_port,
+      to_port: p.to_port ?? p.from_port,
+    }),
     perform: (client, p) => client.ec2.authorizeSecurityGroupIngress({
-      GroupId: p.group_id, CidrIp: p.cidr, FromPort: p.from_port, ToPort: p.to_port ?? p.from_port, IpProtocol: p.protocol ?? 'tcp',
+      GroupId: p.group_id,
+      CidrIp: p.cidr,
+      FromPort: p.from_port,
+      ToPort: p.to_port,
+      IpProtocol: p.protocol,
     }),
   },
 };

package/adapters/github-demo.mjs

@@ -8,38 +8,41 @@
  * with no credentials; swap in `new Octokit({ auth })` for the real thing.
  * @license Apache-2.0
  */
-import crypto from 'node:crypto';
-import { createGate } from '../index.js';
+import { createGate, createEg1Harness } from '../index.js';
 import { createGithubManifest, guardGithubMutation } from './github.js';
 
-const canon = (v) => (v == null ? JSON.stringify(v)
-  : Array.isArray(v) ? `[${v.map(canon).join(',')}]`
-    : typeof v === 'object' ? `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canon(v[k])).join(',')}}`
-      : JSON.stringify(v));
-const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
-const ISSUER = publicKey.export({ type: 'spki', format: 'der' }).toString('base64url');
-let n = 0;
-const mint = (extra = {}) => {
-  const payload = {
-    receipt_id: `gh_${++n}`, subject: 'agent:repo-bot', issuer: 'ep:org:demo', created_at: new Date().toISOString(),
-    claim: { action_type: 'github.repo.delete', owner: 'acme', repo: 'prod', outcome: 'allow_with_signoff', approver: 'ep:approver:cto', ...extra },
-  };
-  return { '@version': 'EP-RECEIPT-v1', payload, signature: { algorithm: 'Ed25519', value: crypto.sign(null, Buffer.from(canon(payload), 'utf8'), privateKey).toString('base64url') } };
-};
+const action = { action_type: 'github.repo.delete', owner: 'acme', repo: 'prod' };
+const harness = createEg1Harness({ action, idPrefix: 'gh' });
 
+const executed = [];
 const octokit = {
-  repos: { delete: async (p) => { console.log(`        !! GitHub API: repos.delete(${p.owner}/${p.repo}) EXECUTED`); return { status: 204 }; } },
+  repos: {
+    delete: async (p) => {
+      executed.push(`${p.owner}/${p.repo}`);
+      return { status: 204 };
+    },
+  },
 };
-const gate = createGate({ manifest: createGithubManifest(), trustedKeys: [ISSUER] });
+const gate = createGate({
+  manifest: createGithubManifest(),
+  trustedKeys: [harness.publicKey],
+  approverKeys: harness.approverKeys,
+  rpId: harness.rpId,
+  allowedOrigins: harness.allowedOrigins,
+  allowEphemeralStore: true,
+});
 const G = (s) => `\x1b[32m${s}\x1b[0m`; const R = (s) => `\x1b[31m${s}\x1b[0m`;
 const line = (s) => console.log(s);
 
 async function attempt(label, params, receipt) {
+  const before = executed.length;
   try {
     const { reliance } = await guardGithubMutation(gate, octokit, { op: 'repo.delete', params, receipt });
-    line(`  ${label} -> ${G('ALLOWED')}  reliance=${reliance.verdict.toUpperCase()}`);
+    const mutation = executed.length === before + 1 ? `  GitHub API=${executed.at(-1)}` : '  GitHub API=NOT CALLED';
+    line(`  ${label} -> ${G('ALLOWED')}  reliance=${reliance.verdict.toUpperCase()}${mutation}`);
   } catch (e) {
-    line(`  ${label} -> ${R(`REFUSED ${e.status || ''}`)} (${e.gate?.reason || e.message})`);
+    const mutation = executed.length === before ? '  GitHub API=NOT CALLED' : '  GitHub API=CALLED';
+    line(`  ${label} -> ${R(`REFUSED ${e.status || ''}`)} (${e.gate?.reason || e.message})${mutation}`);
   }
 }
 
@@ -47,10 +50,10 @@ line('='.repeat(66));
 line('  EMILIA Gate × GitHub — agent tries to delete the production repo');
 line('='.repeat(66));
 await attempt('1. delete acme/prod, no receipt            ', { owner: 'acme', repo: 'prod' }, null);
-const approval = mint();
+const approval = harness.mint({ outcome: 'allow_with_signoff' });
 await attempt('2. delete acme/prod, valid human signoff   ', { owner: 'acme', repo: 'prod' }, approval);
 await attempt('3. same receipt replayed                   ', { owner: 'acme', repo: 'prod' }, approval);
-const reAppro = mint();
+const reAppro = harness.mint({ outcome: 'allow_with_signoff' });
 await attempt('4. approved acme/prod, but targets staging ', { owner: 'acme', repo: 'staging' }, reAppro);
 line('  ' + '-'.repeat(62));
 line('  No receipt, no mutation. The GitHub API is only reached on an allowed line.');

package/adapters/github.js

@@ -12,7 +12,7 @@
  *   import { createGate } from '@emilia-protocol/gate';
  *   import { createGithubManifest, guardGithubMutation } from '@emilia-protocol/gate/adapters/github';
  *
- *   const gate = createGate({ manifest: createGithubManifest(), trustedKeys: [ISSUER] });
+ *   const gate = createGate({ manifest: createGithubManifest(), trustedKeys: [ISSUER], store: sharedConsumptionStore });
  *   const octokit = new Octokit({ auth });
  *   await guardGithubMutation(gate, octokit, {
  *     op: 'repo.delete', params: { owner, repo }, receipt,  // throws if no valid receipt

package/adapters/jira.js

@@ -34,6 +34,7 @@ const OPS = {
   'issue.bulk_delete': {
     selector: { protocol: 'jira', tool: 'bulk_delete_issues' },
     observed: (p) => ({ action_type: 'jira.issue.bulk_delete', project: p.project, jql_hash: hashCanonical(String(p.jql || '').trim()) }),
+    actuator: (p, observed) => ({ ...observed, jql: p.jql }),
     perform: (c, p) => c.bulkDeleteIssues({ project: p.project, jql: p.jql }),
   },
   'project.delete': {

package/adapters/linear.js

@@ -39,6 +39,7 @@ const OPS = {
   'issue.bulk_delete': {
     selector: { protocol: 'linear', tool: 'bulk_delete_issues' },
     observed: (p) => ({ action_type: 'linear.issue.bulk_delete', team: p.team, query_hash: hashCanonical(String(p.query || '').trim()) }),
+    actuator: (p, observed) => ({ ...observed, query: p.query }),
     perform: (c, p) => c.bulkDeleteIssues({ team: p.team, query: p.query }),
   },
   'team.delete': {

package/adapters/salesforce.js

@@ -34,6 +34,7 @@ const OPS = {
   'records.bulk_delete': {
     selector: { protocol: 'salesforce', tool: 'bulk_delete' },
     observed: (p) => ({ action_type: 'salesforce.records.bulk_delete', object: p.object, soql_hash: hashCanonical(String(p.soql || '').trim()) }),
+    actuator: (p, observed) => ({ ...observed, soql: p.soql }),
     perform: (c, p) => c.bulkDelete({ object: p.object, soql: p.soql }),
   },
   'data.export': {

package/adapters/stripe.js

@@ -12,7 +12,7 @@
  *   import { createGate } from '@emilia-protocol/gate';
  *   import { createStripeManifest, guardStripeMutation } from '@emilia-protocol/gate/adapters/stripe';
  *
- *   const gate = createGate({ manifest: createStripeManifest(), trustedKeys: [ISSUER] });
+ *   const gate = createGate({ manifest: createStripeManifest(), trustedKeys: [ISSUER], store: sharedConsumptionStore });
  *   await guardStripeMutation(gate, new Stripe(key), {
  *     op: 'payout.create', params: { amount: 40000, currency: 'usd', destination: 'acct_x' }, receipt,
  *   });

package/adapters/supabase.js

@@ -12,7 +12,7 @@
  *   import { createGate } from '@emilia-protocol/gate';
  *   import { createSupabaseManifest, guardSupabaseMutation, isDestructiveSql } from '@emilia-protocol/gate/adapters/supabase';
  *
- *   const gate = createGate({ manifest: createSupabaseManifest(), trustedKeys: [ISSUER] });
+ *   const gate = createGate({ manifest: createSupabaseManifest(), trustedKeys: [ISSUER], store: sharedConsumptionStore });
  *   // client: anything with .query(sql) (node-postgres / a Supabase RPC wrapper).
  *   await guardSupabaseMutation(gate, client, {
  *     op: 'sql.destructive', params: { sql: 'DELETE FROM payments WHERE id=1', table: 'payments' }, receipt,
@@ -20,6 +20,8 @@
  */
 import { createAdapter, manifestFromPack, hashCanonical } from './_kit.js';
 
+export const RLS_DEFINITION_BINDING_VERSION = 'EP-SUPABASE-RLS-DEFINITION-v1';
+
 const DESTRUCTIVE = /\b(delete|drop|truncate|alter\s+table)\b/i;
 const UPDATE_NO_WHERE = /\bupdate\b(?:(?!\bwhere\b).)*$/is;
 
@@ -34,6 +36,14 @@ export function statementHash(sql) {
   return hashCanonical(String(sql || '').replace(/\s+/g, ' ').trim().toLowerCase());
 }
 
+/** Digest the exact canonical RLS definition without placing it in evidence. */
+export function rlsDefinitionDigest(definition) {
+  return hashCanonical({
+    version: RLS_DEFINITION_BINDING_VERSION,
+    definition,
+  });
+}
+
 export const SUPABASE_ACTION_PACK = Object.freeze([
   Object.freeze({
     id: 'supabase.sql.destructive', label: 'Destructive SQL', action_type: 'supabase.sql.destructive',
@@ -54,7 +64,11 @@ export const SUPABASE_ACTION_PACK = Object.freeze([
     risk: 'critical', receipt_required: true, assurance_class: 'quorum',
     match: { protocol: 'supabase', tool: 'alter_policy' },
     why: 'Changes who can read/write rows. Row-Level-Security changes deserve the two-person rule.',
-    execution_binding: { required_fields: ['action_type', 'table', 'policy'] },
+    execution_binding: {
+      required_fields: [
+        'action_type', 'table', 'policy', 'rls_definition_digest', 'rls_definition_version',
+      ],
+    },
   }),
 ]);
 
@@ -62,6 +76,7 @@ const OPS = {
   'sql.destructive': {
     selector: { protocol: 'supabase', tool: 'execute_sql' },
     observed: (p) => ({ action_type: 'supabase.sql.destructive', statement_hash: statementHash(p.sql) }),
+    actuator: (p, observed) => ({ ...observed, sql: p.sql }),
     perform: (client, p) => client.query(p.sql),
   },
   'data.export': {
@@ -71,7 +86,14 @@ const OPS = {
   },
   'rls.change': {
     selector: { protocol: 'supabase', tool: 'alter_policy' },
-    observed: (p) => ({ action_type: 'supabase.rls.change', table: p.table, policy: p.policy }),
+    observed: (p) => ({
+      action_type: 'supabase.rls.change',
+      table: p.table,
+      policy: p.policy,
+      rls_definition_digest: rlsDefinitionDigest(p.definition),
+      rls_definition_version: RLS_DEFINITION_BINDING_VERSION,
+    }),
+    actuator: (p, observed) => ({ ...observed, definition: p.definition }),
     perform: (client, p) => client.alterPolicy(p.table, p.policy, p.definition),
   },
 };
@@ -96,5 +118,5 @@ export function guardSupabaseMutation(gate, client, args) {
 
 export default {
   SUPABASE_ACTION_PACK, SUPABASE_OPS, createSupabaseManifest, guardSupabaseMutation,
-  isDestructiveSql, statementHash,
+  isDestructiveSql, statementHash, rlsDefinitionDigest, RLS_DEFINITION_BINDING_VERSION,
 };

package/adapters/vercel.js

@@ -5,7 +5,17 @@
  * never reach Vercel without a receipt bound to THIS project. Client injected
  * (the Vercel REST client or a thin wrapper).
  */
-import { createAdapter, manifestFromPack } from './_kit.js';
+import { createAdapter, manifestFromPack, hashCanonical } from './_kit.js';
+
+export const SECRET_VALUE_BINDING_VERSION = 'EP-VERCEL-SECRET-VALUE-v1';
+
+/** Digest an exact secret value for receipt binding; callers must never log it. */
+export function secretValueDigest(value) {
+  return hashCanonical({
+    version: SECRET_VALUE_BINDING_VERSION,
+    value,
+  });
+}
 
 export const VERCEL_ACTION_PACK = Object.freeze([
   Object.freeze({
@@ -27,7 +37,11 @@ export const VERCEL_ACTION_PACK = Object.freeze([
     risk: 'high', receipt_required: true, assurance_class: 'class_a',
     match: { protocol: 'vercel', tool: 'upsert_env' },
     why: 'Changes production secrets/config. Bind project+key+target.',
-    execution_binding: { required_fields: ['action_type', 'project', 'key', 'target'] },
+    execution_binding: {
+      required_fields: [
+        'action_type', 'project', 'key', 'target', 'secret_value_digest', 'secret_value_version',
+      ],
+    },
   }),
 ]);
 
@@ -44,7 +58,15 @@ const OPS = {
   },
   'env.set': {
     selector: { protocol: 'vercel', tool: 'upsert_env' },
-    observed: (p) => ({ action_type: 'vercel.env.set', project: p.project, key: p.key, target: p.target }),
+    observed: (p) => ({
+      action_type: 'vercel.env.set',
+      project: p.project,
+      key: p.key,
+      target: p.target,
+      secret_value_digest: secretValueDigest(p.value),
+      secret_value_version: SECRET_VALUE_BINDING_VERSION,
+    }),
+    actuator: (p, observed) => ({ ...observed, value: p.value }),
     perform: (c, p) => c.upsertEnv({ project: p.project, key: p.key, value: p.value, target: p.target }),
   },
 };
@@ -53,4 +75,11 @@ const adapter = createAdapter({ system: 'vercel', ops: OPS });
 export const VERCEL_OPS = adapter.OPS;
 export function createVercelManifest(extra = []) { return manifestFromPack(VERCEL_ACTION_PACK, extra); }
 export function guardVercelMutation(gate, client, args) { return adapter.guard(gate, client, args); }
-export default { VERCEL_ACTION_PACK, VERCEL_OPS, createVercelManifest, guardVercelMutation };
+export default {
+  VERCEL_ACTION_PACK,
+  VERCEL_OPS,
+  SECRET_VALUE_BINDING_VERSION,
+  secretValueDigest,
+  createVercelManifest,
+  guardVercelMutation,
+};

package/aec-execution.js

@@ -9,9 +9,7 @@
  */
 import { createEvidenceLog, verifyEvidenceRecord } from './evidence.js';
 import { MemoryConsumptionStore } from './store.js';
-
-const { verifyAuthorizationChain } = await import('@emilia-protocol/verify/evidence-chain')
-  .catch(() => import('../verify/evidence-chain.js'));
+import { verifyAuthorizationChain } from '@emilia-protocol/verify/evidence-chain';
 
 const HUMAN_FLOORS = new Set(['class_a', 'quorum', 'class_a_or_quorum']);
 const HEX_256 = /^[0-9a-f]{64}$/;