@atrib/attest 0.1.0 → 0.2.0

package/README.md

@@ -54,18 +54,20 @@ attest({
   provenance_token?: string,
   tool_name?: string,
   args_hash?: string,
+  args_salt?: string,            // base64url 16-byte salt; requires args_hash
   result_hash?: string,
+  result_salt?: string,          // base64url 16-byte salt; requires result_hash
   producer?: string,              // sidecar label override; defaults to 'atrib-attest'
 })
 ```
 
 ### Ref mapping
 
-| `ref` argument | Signed record | Signed field carried |
-| --- | --- | --- |
-| absent | observation | none |
-| `{ kind: "annotates", target, ... }` | annotation | signed `annotates` field |
-| `{ kind: "revises", target, reason, ... }` (`reason` required) | revision | signed `revises` field |
+| `ref` argument                                                 | Signed record | Signed field carried     |
+| -------------------------------------------------------------- | ------------- | ------------------------ |
+| absent                                                         | observation   | none                     |
+| `{ kind: "annotates", target, ... }`                           | annotation    | signed `annotates` field |
+| `{ kind: "revises", target, reason, ... }` (`reason` required) | revision      | signed `revises` field   |
 
 The three shapes route through the same `handleEmit` funnel used by the
 legacy tools. There is no separate signing path for `attest`: the ref
@@ -110,10 +112,10 @@ re-export shims.
 
 ```typescript
 import {
-  createAtribAttestServer,       // mounts the four-tool write union
-  createAtribEmitServer,          // legacy factory; also mounts attest
-  createAtribAnnotateServer,      // legacy factory; also mounts attest
-  createAtribReviseServer,        // legacy factory; also mounts attest
+  createAtribAttestServer, // mounts the four-tool write union
+  createAtribEmitServer, // legacy factory; also mounts attest
+  createAtribAnnotateServer, // legacy factory; also mounts attest
+  createAtribReviseServer, // legacy factory; also mounts attest
   handleAttest,
   attestInProcess,
 
@@ -123,7 +125,7 @@ import {
   EmitInput,
   resolveKey,
   emitSessionCheckpoint,
-} from "@atrib/attest";
+} from '@atrib/attest'
 ```
 
 Each legacy factory (`createAtribEmitServer`, `createAtribAnnotateServer`,
@@ -160,6 +162,11 @@ verb that contract is the most important thing to know:
   carries only the replay-checkable `args_hash` commitment over it. The
   public log stores the 90-byte commitment entry (record hash, creator key,
   context_id, timestamp, event_type byte), never the content.
+- **Salted direct commitments.** `args_salt` and `result_salt` let direct
+  attest callers carry the same salted commitment posture as middleware.
+  Each salt must be canonical base64url for exactly 16 bytes and requires its
+  matching explicit hash. The shared `@atrib/mcp` commitment helper computes
+  and verifies the bytes used by both paths.
 - **Refused writes are loud, not silent.** A malformed call (unknown
   `ref.kind`, missing revises reason, a `ref`/content contradiction, a
   provenance_token off genesis, or no resolvable signing key) returns

package/dist/attest.d.ts

@@ -24,7 +24,9 @@ export declare const AttestInput: z.ZodObject<{
     provenance_token: z.ZodOptional<z.ZodString>;
     tool_name: z.ZodOptional<z.ZodString>;
     args_hash: z.ZodOptional<z.ZodString>;
+    args_salt: z.ZodOptional<z.ZodString>;
     result_hash: z.ZodOptional<z.ZodString>;
+    result_salt: z.ZodOptional<z.ZodString>;
     producer: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type AttestInputT = z.infer<typeof AttestInput>;
@@ -46,7 +48,9 @@ export interface MappedAttestInput {
         revises?: string;
         tool_name?: string;
         args_hash?: string;
+        args_salt?: string;
         result_hash?: string;
+        result_salt?: string;
     };
 }
 export interface AttestMappingRefusal {

package/dist/attest.js

@@ -16,19 +16,29 @@
 // (matching what atrib-annotate / atrib-revise compose today), so the
 // D099 default args_hash commitment is byte-identical across both names.
 import { z } from 'zod';
-import { EVENT_TYPE_ANNOTATION_URI, EVENT_TYPE_REVISION_URI, SHA256_REF_PATTERN, } from '@atrib/mcp';
+import { EVENT_TYPE_ANNOTATION_URI, EVENT_TYPE_REVISION_URI, SHA256_REF_PATTERN } from '@atrib/mcp';
 const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
 // 16 bytes encoded as base64url with no padding = 22 chars per spec §1.2.6.
 const PROVENANCE_TOKEN_PATTERN = /^[A-Za-z0-9_-]{22}$/;
 const OBSERVATION_URI = 'https://atrib.dev/v1/types/observation';
 export const AttestRef = z.object({
-    kind: z.enum(['annotates', 'revises']).describe("Declared-relationship kind. 'annotates' marks a past record's importance " +
+    kind: z
+        .enum(['annotates', 'revises'])
+        .describe("Declared-relationship kind. 'annotates' marks a past record's importance " +
         "and meaning (spec §1.2.7 / D058); 'revises' supersedes a prior position " +
         'with a stated reason (spec §1.2.9 / D059). Omit `ref` entirely for a ' +
         'plain observation.'),
-    target: z.string().regex(SHA256_REF_PATTERN).describe("'sha256:<64-hex>' record_hash the relationship points at. The target can " +
+    target: z
+        .string()
+        .regex(SHA256_REF_PATTERN)
+        .describe("'sha256:<64-hex>' record_hash the relationship points at. The target can " +
         "be any prior record (yours or another agent's)."),
-    reason: z.string().min(1).max(4096).optional().describe("Why the position changed. REQUIRED when kind is 'revises'; composed into " +
+    reason: z
+        .string()
+        .min(1)
+        .max(4096)
+        .optional()
+        .describe("Why the position changed. REQUIRED when kind is 'revises'; composed into " +
         'the content body exactly as atrib-revise composes it today.'),
 });
 export const AttestInput = z.object({
@@ -85,11 +95,21 @@ export const AttestInput = z.object({
         .optional()
         .describe('Optional §8.3 args_hash commitment override. When omitted, attest signs ' +
         'sha256(JCS(content)) per D099, identical to the legacy write names.'),
+    args_salt: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{22}$/)
+        .optional()
+        .describe('Optional base64url 16-byte salt paired with args_hash per §8.3.'),
     result_hash: z
         .string()
         .regex(SHA256_REF_PATTERN)
         .optional()
         .describe('Optional §8.3 result_hash commitment, unchanged from the legacy emit tool.'),
+    result_salt: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{22}$/)
+        .optional()
+        .describe('Optional base64url 16-byte salt paired with result_hash per §8.3.'),
     producer: z
         .string()
         .min(1)
@@ -122,7 +142,9 @@ export function mapAttestInput(input) {
         ...(input.provenance_token ? { provenance_token: input.provenance_token } : {}),
         ...(input.tool_name ? { tool_name: input.tool_name } : {}),
         ...(input.args_hash ? { args_hash: input.args_hash } : {}),
+        ...(input.args_salt ? { args_salt: input.args_salt } : {}),
         ...(input.result_hash ? { result_hash: input.result_hash } : {}),
+        ...(input.result_salt ? { result_salt: input.result_salt } : {}),
     };
     if (!input.ref) {
         const conflict = contentRefConflicts(input.content, undefined);
@@ -185,7 +207,7 @@ function contentRefConflicts(content, ref) {
     if (!ref) {
         if (contentAnnotates !== undefined || contentRevises !== undefined) {
             return ('content carries a relationship field (annotates/revises) but no ref was declared; ' +
-                "declare ref: { kind, target } instead of embedding the relationship in content");
+                'declare ref: { kind, target } instead of embedding the relationship in content');
         }
         return null;
     }
@@ -205,9 +227,7 @@ function contentRefConflicts(content, ref) {
     if (contentRevises !== undefined && contentRevises !== ref.target) {
         return `content.revises (${String(contentRevises)}) contradicts ref.target (${ref.target})`;
     }
-    if (contentReason !== undefined &&
-        ref.reason !== undefined &&
-        contentReason !== ref.reason) {
+    if (contentReason !== undefined && ref.reason !== undefined && contentReason !== ref.reason) {
         return 'content.reason contradicts ref.reason';
     }
     return null;

package/dist/index.d.ts

@@ -18,7 +18,9 @@ declare const EmitInput: z.ZodObject<{
     revises: z.ZodOptional<z.ZodString>;
     tool_name: z.ZodOptional<z.ZodString>;
     args_hash: z.ZodOptional<z.ZodString>;
+    args_salt: z.ZodOptional<z.ZodString>;
     result_hash: z.ZodOptional<z.ZodString>;
+    result_salt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type EmitSignedOutput = {
     signed: true;
@@ -308,5 +310,5 @@ export { AttestInput, AttestRef, mapAttestInput, isAttestMappingRefusal } from '
 export type { AttestInputT, MappedAttestInput, AttestMappingRefusal } from './attest.js';
 export { AnnotateInput, Importance, createAtribAnnotateServer, registerAnnotateTool, } from './annotate.js';
 export type { AtribAnnotateServer, CreateAtribAnnotateServerOptions } from './annotate.js';
-export { ReviseInput, createAtribReviseServer, registerReviseTool, } from './revise.js';
+export { ReviseInput, createAtribReviseServer, registerReviseTool } from './revise.js';
 export type { AtribReviseServer, CreateAtribReviseServerOptions } from './revise.js';

package/dist/index.js

@@ -24,7 +24,7 @@ import { resolveKey } from './keys.js';
 import { filterResolvableInformedBy } from './reference-resolution.js';
 import { buildAndSignEmitRecord } from './sign.js';
 import { mirrorRecord } from './storage.js';
-import { AttestInput, isAttestMappingRefusal, mapAttestInput, } from './attest.js';
+import { AttestInput, isAttestMappingRefusal, mapAttestInput } from './attest.js';
 import { registerAnnotateTool } from './annotate.js';
 import { registerReviseTool } from './revise.js';
 // Read-side mirror inheritance: ATRIB_AUTOCHAIN_SOURCE points at the file
@@ -41,6 +41,7 @@ function readMirrorPath() {
 const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
 // 16 bytes encoded as base64url with no padding = 22 chars per spec §1.2.6.
 const PROVENANCE_TOKEN_PATTERN = /^[A-Za-z0-9_-]{22}$/;
+const COMMITMENT_SALT_PATTERN = /^[A-Za-z0-9_-]{22}$/;
 const DEFAULT_KEY_RESOLVE_RETRY_MS = 30_000;
 const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
 function keyResolveRetryMs() {
@@ -138,17 +139,24 @@ const EmitInput = z.object({
         .optional()
         .describe('Optional §8.3 args_hash commitment. Format: "sha256:" + 64 lowercase hex. Lets ' +
         'emit-signed records carry a commitment to canonical args bytes for downstream ' +
-        'consumers (e.g. recall filtering by args_hash, or replay detection). Salted vs ' +
-        'plain forms hash identically on the wire; the salt (when used) is carried in the ' +
-        'separate args_salt field, which this surface does not yet expose.'),
+        'consumers (e.g. recall filtering by args_hash, or replay detection).'),
+    args_salt: z
+        .string()
+        .regex(COMMITMENT_SALT_PATTERN)
+        .optional()
+        .describe('Optional base64url 16-byte salt paired with args_hash per §8.3.'),
     result_hash: z
         .string()
         .regex(SHA256_REF_PATTERN)
         .optional()
         .describe('Optional §8.3 result_hash commitment. Format: "sha256:" + 64 lowercase hex. Lets ' +
         'emit-signed records carry a commitment to canonical result bytes for downstream ' +
-        'consumers. Salted vs plain forms hash identically on the wire; the salt (when used) ' +
-        'is carried in the separate result_salt field, which this surface does not yet expose.'),
+        'consumers.'),
+    result_salt: z
+        .string()
+        .regex(COMMITMENT_SALT_PATTERN)
+        .optional()
+        .describe('Optional base64url 16-byte salt paired with result_hash per §8.3.'),
 });
 const DEFAULT_LOCAL_SUBSTRATE_DEGRADATION = {
     if_unavailable: 'sign locally in producer and continue without coordinator receipt',
@@ -212,7 +220,7 @@ export function registerEmitTool(mcp, deps) {
  */
 export function registerAttestTool(mcp, deps) {
     mcp.registerTool('attest', {
-        description: 'Make a signed statement now: atrib\'s write verb. Signs an observation by default; ' +
+        description: "Make a signed statement now: atrib's write verb. Signs an observation by default; " +
             'declare ref: { kind: "annotates", target } to mark a past record\'s importance, or ' +
             'ref: { kind: "revises", target, reason } to supersede a prior position. One handler ' +
             'behind the legacy emit / atrib-annotate / atrib-revise names; records are ' +
@@ -475,11 +483,15 @@ async function handleEmit({ input, key, queue, producer, logEndpoint, recordRefe
             revises: input.revises,
             toolName: input.tool_name,
             argsHash: input.args_hash,
+            argsSalt: input.args_salt,
             resultHash: input.result_hash,
+            resultSalt: input.result_salt,
         });
     }
     catch (e) {
-        return refusalOutput(contextId, [`signing failed: ${e instanceof Error ? e.message : String(e)}`]);
+        return refusalOutput(contextId, [
+            `signing failed: ${e instanceof Error ? e.message : String(e)}`,
+        ]);
     }
     const recordHash = hashRecord(record);
     const unsignedRecordBody = unsignedRecordBodyFromSigned(record);
@@ -1025,4 +1037,4 @@ export { AttestInput, AttestRef, mapAttestInput, isAttestMappingRefusal } from '
 // Legacy specialized writers, kept as permanent aliases over the attest
 // funnel. The @atrib/annotate and @atrib/revise packages re-export these.
 export { AnnotateInput, Importance, createAtribAnnotateServer, registerAnnotateTool, } from './annotate.js';
-export { ReviseInput, createAtribReviseServer, registerReviseTool, } from './revise.js';
+export { ReviseInput, createAtribReviseServer, registerReviseTool } from './revise.js';

package/dist/sign.d.ts

@@ -46,11 +46,15 @@ export interface BuildEmitRecordInput {
      * replay-checkable without exposing the body to the public log.
      */
     argsHash?: string | undefined;
+    /** Optional 16-byte base64url salt paired with argsHash. */
+    argsSalt?: string | undefined;
     /**
      * Optional §8.3 result_hash commitment. Same posture semantics and wire
      * format as args_hash, but commits to the tool result bytes.
      */
     resultHash?: string | undefined;
+    /** Optional 16-byte base64url salt paired with resultHash. */
+    resultSalt?: string | undefined;
 }
 /**
  * Build, sign, and return a complete AtribRecord ready for submission.

package/dist/sign.js

@@ -23,6 +23,12 @@ const encoder = new TextEncoder();
  * Pure aside from the signing primitive itself; no network I/O here.
  */
 export async function buildAndSignEmitRecord(input) {
+    if (input.argsSalt && !input.argsHash) {
+        throw new TypeError('args_salt requires an explicit args_hash');
+    }
+    if (input.resultSalt && !input.resultHash) {
+        throw new TypeError('result_salt requires result_hash');
+    }
     const publicKey = base64urlEncode(await getPublicKey(input.privateKey));
     const toolName = leafOfEventTypeUri(input.eventType);
     const contentId = computeContentId(SYNTHETIC_SERVER_URL, toolName);
@@ -30,9 +36,7 @@ export async function buildAndSignEmitRecord(input) {
     // informed_by must be sorted lexicographically per §1.2.5 to keep the
     // canonical form stable across emitters. Omitted entirely (not null,
     // not empty) when no references are given, presence affects JCS.
-    const informedBySorted = input.informedBy && input.informedBy.length > 0
-        ? [...input.informedBy].sort()
-        : undefined;
+    const informedBySorted = input.informedBy && input.informedBy.length > 0 ? [...input.informedBy].sort() : undefined;
     const record = {
         spec_version: 'atrib/1.0',
         content_id: contentId,
@@ -45,8 +49,10 @@ export async function buildAndSignEmitRecord(input) {
         ...(informedBySorted ? { informed_by: informedBySorted } : {}),
         ...(input.annotates ? { annotates: input.annotates } : {}),
         ...(argsHash ? { args_hash: argsHash } : {}),
+        ...(input.argsSalt ? { args_salt: input.argsSalt } : {}),
         ...(input.provenanceToken ? { provenance_token: input.provenanceToken } : {}),
         ...(input.resultHash ? { result_hash: input.resultHash } : {}),
+        ...(input.resultSalt ? { result_salt: input.resultSalt } : {}),
         ...(input.revises ? { revises: input.revises } : {}),
         ...(input.toolName ? { tool_name: input.toolName } : {}),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrib/attest",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for atrib's write verb. One attest tool signs observations, annotations, and revisions; the legacy emit, atrib-annotate, and atrib-revise tool names stay mounted as aliases over the same handler.",
   "keywords": [
     "atrib",
@@ -45,13 +45,13 @@
     "@noble/hashes": "^2.2.0",
     "canonicalize": "^3.0.0",
     "zod": "^3.25.76",
-    "@atrib/mcp": "0.21.0"
+    "@atrib/mcp": "0.22.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
-    "tsx": "^4.22.4",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.10"
   },
   "files": [
     "dist"