cellar-door-entry

cellar-door-entry

𓉸 Passage Protocol · exit-door · entry-door · mcp · langchain · vercel · eliza · eas · erc-8004 · sign · python

⚠️ Pre-release software — no formal security audit has been conducted. This project is published for transparency, review, and community feedback. It should not be used in production systems where security guarantees are required. If you find a vulnerability, please report it to [e-mail].

The arrival side. Verify where an agent came from and decide whether to let it in.

📌 v1.2 Stable Snapshot — Tagged reference point before v2 policy engine changes.

Ecosystem

Package	Language	Description
cellar-door-exit	TypeScript	Core protocol (reference impl)
cellar-door-exit	Python	Core protocol
cellar-door-entry	TypeScript	Arrival/entry markers ← you are here
@cellar-door/langchain	TypeScript	LangChain integration
cellar-door-langchain	Python	LangChain integration
@cellar-door/vercel-ai-sdk	TypeScript	Vercel AI SDK
@cellar-door/mcp-server	TypeScript	MCP server
@cellar-door/eliza	TypeScript	ElizaOS plugin
@cellar-door/eas	TypeScript	EAS attestation anchoring
@cellar-door/erc-8004	TypeScript	ERC-8004 identity/reputation
@cellar-door/sign-protocol	TypeScript	Sign Protocol attestation

Paper · Website

Quick Start

npm install cellar-door-entry cellar-door-exit

import { quickExit, toJSON } from "cellar-door-exit";
import { quickEntry } from "cellar-door-entry";

// Agent exits Platform A
const { marker: exitMarker } = await quickExit("https://platform-a.example.com");
const exitJson = toJSON(exitMarker);

// Agent arrives at Platform B
const { arrivalMarker, continuity } = quickEntry(exitJson, "https://platform-b.example.com");

console.log(continuity.valid);           // true
console.log(arrivalMarker.departureRef); // urn:exit:...
console.log(arrivalMarker.subject);      // did:key:z6Mk...

The Passage Flow

The complete pipeline for agent passage between platforms:

EXIT → verify departure → evaluate admission → create arrival → sign → verify continuity → claim

import { quickExit, toJSON, generateIdentity } from "cellar-door-exit";
import {
  createArrivalMarker,
  signArrivalMarker,
  evaluateAdmission,
  OPEN_DOOR,
  scopeFromExitMarker,
  InMemoryClaimStore,
  verifyTransfer,
  validateArrivalMarker,
} from "cellar-door-entry";

// 1. Agent exits Platform A
const { marker: exitMarker } = await quickExit("https://platform-a.example.com");

// 2. Evaluate admission policy
const admission = evaluateAdmission(exitMarker, OPEN_DOOR);
if (!admission.admitted) throw new Error(`Denied: ${admission.reasons.join(", ")}`);

// 3. Derive capability scope from exit modules
const scope = scopeFromExitMarker(exitMarker);

// 4. Create and sign arrival marker
const arrival = createArrivalMarker(exitMarker, "https://platform-b.example.com", {
  capabilityScope: scope,
});
const dest = generateIdentity();
const signed = signArrivalMarker(arrival, dest.privateKey, dest.publicKey);

// 5. Claim the departure (prevent replay)
const store = new InMemoryClaimStore();
store.claim(exitMarker.id, signed.id);

// 6. Verify the full passage
const passage = verifyTransfer(exitMarker, signed);
console.log(passage.verified); // true

// 7. Validate marker structure
const valid = validateArrivalMarker(signed);
console.log(valid.valid); // true

Policy Engine (v2)

Composable, fail-closed policy engine for admission decisions. Cryptographic signature verification is built into the ceremony.

import { createPolicy, admit, CAUTIOUS, REQUIRE_MUTUAL } from "cellar-door-entry";
import { quickExit, generateKeyPair } from "cellar-door-exit";

// Build a policy with the fluent API
const policy = createPolicy("my-platform")
  .requireVerifiedDeparture()      // cryptographic proof required
  .onSelfOnly("probation")         // self-attestation gets probation
  .maxAge("24h")                   // reject stale markers
  .allowMinting({ requireJustification: true })  // fresh agents OK
  .build();

// Admit an arriving agent
const { marker } = await quickExit("https://origin.example.com");
const platformKeys = generateKeyPair();
const result = await admit(marker, {
  policy,
  platformIdentity: platformKeys,   // enables counter-signing
  destination: "https://my-platform.example.com",
});

if (result.admission.admitted) {
  console.log(result.arrivalMarker.id);              // urn:entry:...
  console.log(result.admission.counterSigned);        // true
  console.log(result.admission.policyApplied);        // "my-platform"
  console.log(result.counterSignedExitMarker);        // exit marker with platform's counter-signature
}

Preset Policies

Preset	Description
CAUTIOUS	Require verified departure, probation for self-only
REQUIRE_MUTUAL	Require counter-signed (mutual) markers
REQUIRE_MUTUAL_WITH_ONRAMP	Mutual required OR minting allowed (antitrust-safe)
PERMISSIVE	Accept most markers, probation for unverified
LOCKDOWN	Reject everything

Minting

Create arrival records for agents with no departure history:

import { mintAgent, bulkMint, createPolicy } from "cellar-door-entry";

const policy = createPolicy("onboarding")
  .allowMinting({ requireJustification: true })
  .build();

// Single mint
const result = await mintAgent({
  subjectDid: "did:key:z6MkNewAgent",
  justification: "Platform bootstrap",
  policy,
});

// Bulk migration
const bulk = await bulkMint(
  [{ subjectDid: "did:key:z6Mk1", justification: "Migration" }],
  { policy }
);

Events

import { AdmissionEventEmitter } from "cellar-door-entry";

const emitter = new AdmissionEventEmitter({
  onError: (err, event) => auditLog.error(event.type, err),
});

emitter.on("agent:admitted", ({ record }) => { /* audit */ });
emitter.on("agent:rejected", ({ record }) => { /* alert */ });
emitter.on("agent:quarantined", ({ record }) => { /* review queue */ });
emitter.on("agent:minted", ({ record }) => { /* onboarding */ });

await admit(marker, { policy, emitter });

SQLite Claim Store

Production-ready claim tracking with WAL mode and GDPR erasure:

import { SqliteClaimStore } from "cellar-door-entry";

const store = new SqliteClaimStore("./claims.db");
await admit(marker, { policy, store });

// GDPR: erase all records for a subject
await store.eraseSubject("did:key:z6MkAgent");

// Stats
const stats = await store.stats();

Modules (v1)

Simple Admission Policy

Declarative rules for basic admission decisions.

import { evaluateAdmission, OPEN_DOOR, STRICT, EMERGENCY_ONLY } from "cellar-door-entry";
import type { AdmissionPolicy } from "cellar-door-entry";

// Preset policies
evaluateAdmission(exitMarker, OPEN_DOOR);       // Accept if signed
evaluateAdmission(exitMarker, STRICT);           // Voluntary, <24h, modules required
evaluateAdmission(exitMarker, EMERGENCY_ONLY);   // Only emergency exits

// Custom policy
const policy: AdmissionPolicy = {
  requireVerifiedDeparture: true,
  maxDepartureAge: 3_600_000,          // 1 hour
  allowedExitTypes: ["voluntary"],
  requiredModules: ["lineage"],
};
const result = evaluateAdmission(exitMarker, policy);
// → { admitted: boolean, conditions: string[], reasons: string[] }

Probation

Track probationary status on arrival markers.

import { createProbationaryArrival, isProbationComplete } from "cellar-door-entry";

const arrival = createProbationaryArrival(exitMarker, "https://platform-b.example.com", {
  duration: 30 * 86_400_000,  // 30 days
  restrictions: ["no-api-write", "limited-storage"],
  reviewRequired: true,
});

// Check later
isProbationComplete(arrival);                          // false (too early)
isProbationComplete(arrival, new Date("2026-04-01"));  // true (30+ days later)

Capability Scope

Determine what the arriving agent can do.

import { scopeFromExitMarker, createRestrictedScope, mergeScopes } from "cellar-door-entry";

// Derive from EXIT marker modules
const scope = scopeFromExitMarker(exitMarker);
// → { allowed: ["basic-interaction", "identity-continuity", ...], denied: [] }

// Manual restriction
const restricted = createRestrictedScope(["read"], ["write"], "2026-12-31T00:00:00Z");

// Merge (denied wins)
const merged = mergeScopes(scope, restricted);

Claim Tracking

Prevent replay attacks; each EXIT marker can only be claimed once.

import { InMemoryClaimStore } from "cellar-door-entry";

const store = new InMemoryClaimStore();
store.claim("urn:exit:abc", "urn:entry:xyz");  // true (claimed)
store.claim("urn:exit:abc", "urn:entry:new");  // false (already claimed)
store.isClaimed("urn:exit:abc");               // true
store.revoke("urn:entry:xyz");                 // unclaims the exit

Implement the ClaimStore interface for production backends (Redis, DB, ledger).

Revocation

Revoke arrivals after the fact.

import { createRevocationMarker, verifyRevocationMarker, isRevoked } from "cellar-door-entry";

const revocation = createRevocationMarker(signedArrival, "fraud detected", privateKey, publicKey);
verifyRevocationMarker(revocation);           // { valid: true, errors: [] }
isRevoked(signedArrival.id, [revocation]);    // true

Passage Verification

End-to-end verification of the EXIT → ENTRY chain.

Note: The API currently exports verifyTransfer(). This will be renamed to verifyPassage() in v0.2.0.

import { verifyTransfer } from "cellar-door-entry";

const record = verifyTransfer(exitMarker, signedArrival);
// → { verified: boolean, errors: [], passageTime: 1234, continuity: {...} }

Input Validation

Validate arrival marker structure and fields.

import { validateArrivalMarker } from "cellar-door-entry";

const result = validateArrivalMarker(marker);
// Checks: context, id format, DID format, timestamp, size limits, etc.

API Reference

Function	Description
verifyDeparture(exitMarker)	Verify an EXIT marker, return structured result
verifyDepartureJSON(json)	Parse and verify an EXIT marker from JSON
createArrivalMarker(exit, destination, opts?)	Create a linked arrival marker
signArrivalMarker(marker, privateKey, publicKey)	Sign an arrival marker with Ed25519
verifyArrivalMarker(marker)	Verify an arrival marker's signature
verifyContinuity(exit, arrival)	Verify the link between departure and arrival
quickEntry(exitJson, destination, opts?)	One-shot: parse, verify, create, sign, check continuity
evaluateAdmission(exitMarker, policy, now?)	Evaluate admission against a policy
createProbationaryArrival(exit, dest, config, opts?)	Create arrival with probation
isProbationComplete(arrival, now?)	Check if probation has elapsed
scopeFromExitMarker(marker)	Extract capabilities from EXIT modules
createRestrictedScope(allowed, denied, expires?)	Create a capability scope
mergeScopes(a, b)	Merge two scopes (denied wins)
InMemoryClaimStore	In-memory claim tracking
createRevocationMarker(arrival, reason, privKey, pubKey)	Create a signed revocation
verifyRevocationMarker(marker)	Verify revocation signature
isRevoked(arrivalId, revocations)	Check if an arrival is revoked
verifyTransfer(exit, arrival)	Full end-to-end passage verification
validateArrivalMarker(marker)	Validate marker structure and fields

Continuity Checks

verifyContinuity validates:

• Reference: Arrival's departureRef matches the EXIT marker's id
• Subject: Same DID on both markers
• Origin: Arrival's departureOrigin matches EXIT's origin
• Temporal: Arrival timestamp is after departure timestamp
• Cryptographic: EXIT marker signature is valid

License

Apache-2.0