@passportsign/core 0.1.0

package/src/dsse.ts

@@ -0,0 +1,91 @@
+/**
+ * DSSE (Dead Simple Signing Envelope) envelope builder.
+ *
+ * Per-binding ephemeral ECDSA P-256 key — the private key is discarded
+ * after signing. The DSSE signature is a Rekor schema requirement, not
+ * a trust mechanism. The actual authentication for passportsign comes
+ * from the zkPassport proof + GitHub gist evidence carried inside the
+ * statement's predicate, not from this signature.
+ *
+ * Spec: https://github.com/secure-systems-lab/dsse/blob/master/protocol.md
+ *
+ * Note on key algorithm choice: ECDSA P-256 over SHA-256 is what
+ * Rekor's public instance accepts for intoto v0.0.2 entries. Ed25519
+ * is in the DSSE spec but the public Rekor's verification path rejected
+ * it during the Day 5 smoke test (500 "error generating canonicalized
+ * entry"). See `docs/v0-acceptance.md` Day 5 evidence.
+ */
+
+import { createSign, generateKeyPairSync } from 'node:crypto';
+
+export const DSSE_VERSION = 'DSSEv1';
+export const IN_TOTO_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+
+export interface DsseSignature {
+  /** Single-base64 of the raw signature bytes. */
+  sig: string;
+  /** PEM-encoded SubjectPublicKeyInfo. */
+  publicKey: string;
+  /** Optional key identifier. Omit (don't pass empty string) when not set. */
+  keyid?: string;
+}
+
+export interface DsseEnvelope {
+  /** Media type of the payload (e.g. `application/vnd.in-toto+json`). */
+  payloadType: string;
+  /** Single-base64 of the raw payload bytes. */
+  payload: string;
+  signatures: DsseSignature[];
+}
+
+/**
+ * DSSE Pre-Authentication Encoding (PAE):
+ *
+ *   "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+ *
+ * Where SP is a single 0x20 space, LEN is the ASCII-decimal length of
+ * the following byte string.
+ */
+export function pae(type: string, body: Uint8Array): Uint8Array {
+  const typeBytes = new TextEncoder().encode(type);
+  const prefix = `${DSSE_VERSION} ${typeBytes.length} ${type} ${body.length} `;
+  const prefixBytes = new TextEncoder().encode(prefix);
+  const out = new Uint8Array(prefixBytes.length + body.length);
+  out.set(prefixBytes);
+  out.set(body, prefixBytes.length);
+  return out;
+}
+
+export interface SignEnvelopeResult {
+  envelope: DsseEnvelope;
+  /** PEM of the ephemeral public key (also embedded in envelope.signatures[0].publicKey). */
+  publicKeyPem: string;
+}
+
+/**
+ * Generate an ephemeral ECDSA P-256 keypair, sign PAE(payloadType,
+ * payload), and return a DSSE envelope. The private key is discarded
+ * before return.
+ */
+export function signEnvelope(payload: Uint8Array, payloadType: string): SignEnvelopeResult {
+  const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
+  const paeBytes = pae(payloadType, payload);
+  const signer = createSign('SHA256');
+  signer.update(Buffer.from(paeBytes));
+  const sigBuf = signer.sign(privateKey);
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }) as string;
+
+  return {
+    envelope: {
+      payloadType,
+      payload: Buffer.from(payload).toString('base64'),
+      signatures: [
+        {
+          sig: sigBuf.toString('base64'),
+          publicKey: publicKeyPem,
+        },
+      ],
+    },
+    publicKeyPem,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,37 @@
+/**
+ * §4 error vocabulary — the set of failure codes a bind/verify call can
+ * surface to a caller. Verbatim from `docs/passportsign.md` §4.
+ *
+ * Callers should `catch` `PassportsignError` and branch on `.code`. The
+ * `cause` field carries the underlying error (HTTP response body, SDK
+ * error, etc.) for logging — never for client display, since it may
+ * include identifying data.
+ */
+
+export const ERROR_CODES = [
+  'username_invalid',
+  'binding_pending_expired',
+  'gist_not_found',
+  'gist_wrong_content',
+  'gist_wrong_owner',
+  'gist_predates_init',
+  'proof_invalid',
+  'proof_scope_mismatch',
+  'proof_missing_personhood',
+  'log_submission_failed',
+  'internal_error',
+] as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+export class PassportsignError extends Error {
+  readonly code: ErrorCode;
+  override readonly cause: unknown;
+
+  constructor(code: ErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.name = 'PassportsignError';
+    this.code = code;
+    this.cause = cause;
+  }
+}

package/src/github.ts

@@ -0,0 +1,196 @@
+/**
+ * GitHub gist control check per spec §3 step 5 and §14 "The gist control check."
+ *
+ * The honest semantic claim is: at the moment we checked, the named user
+ * controlled a public gist with the expected filename and content. We
+ * capture `html_url`, `updated_at`, and a SHA-256 of the content so the
+ * evidence is independently re-checkable later (e.g. via the Wayback
+ * Machine).
+ *
+ * The optional `token` is **purely for rate-limit headroom** — it
+ * carries zero special access. Unauth'd: 60 req/hr; with token: 5000.
+ */
+
+import { createHash } from 'node:crypto';
+import { PassportsignError } from './errors.js';
+
+export interface GistEvidence {
+  url: string;
+  content_sha256: string;
+  updated_at: string;
+}
+
+export interface CheckGistOptions {
+  username: string;
+  expected_filename: string;
+  expected_content: string;
+  not_before: Date;
+  token?: string;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}
+
+interface GistFile {
+  filename?: string;
+  content?: string;
+}
+
+interface GistSummary {
+  id: string;
+  html_url: string;
+  updated_at: string;
+  owner?: { login?: string } | null;
+  files: Record<string, GistFile>;
+}
+
+const DEFAULT_BASE_URL = 'https://api.github.com';
+const GIST_LIST_PER_PAGE = 100;
+
+function sha256Hex(content: string): string {
+  return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+function authHeaders(token: string | undefined): Record<string, string> {
+  return {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'passportsign-cli',
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  };
+}
+
+export async function checkGistControl(opts: CheckGistOptions): Promise<GistEvidence> {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  const baseUrl = opts.baseUrl ?? DEFAULT_BASE_URL;
+  const headers = authHeaders(opts.token);
+
+  if (opts.username.length === 0) {
+    throw new PassportsignError('username_invalid', 'username must be non-empty');
+  }
+
+  // Step 1: list the user's gists, filter by filename.
+  const listUrl = `${baseUrl}/users/${encodeURIComponent(opts.username)}/gists?per_page=${GIST_LIST_PER_PAGE}`;
+  let listResponse: Response;
+  try {
+    listResponse = await fetchImpl(listUrl, { headers });
+  } catch (err) {
+    throw new PassportsignError(
+      'internal_error',
+      `GitHub list-gists request failed: ${err instanceof Error ? err.message : String(err)}`,
+      err,
+    );
+  }
+
+  if (listResponse.status === 404) {
+    throw new PassportsignError(
+      'username_invalid',
+      `GitHub user '${opts.username}' not found`,
+    );
+  }
+  if (!listResponse.ok) {
+    throw new PassportsignError(
+      'internal_error',
+      `GitHub list-gists returned HTTP ${listResponse.status}`,
+    );
+  }
+
+  let listBody: unknown;
+  try {
+    listBody = await listResponse.json();
+  } catch (err) {
+    throw new PassportsignError(
+      'internal_error',
+      'GitHub list-gists returned non-JSON',
+      err,
+    );
+  }
+  if (!Array.isArray(listBody)) {
+    throw new PassportsignError(
+      'internal_error',
+      'GitHub list-gists did not return an array',
+    );
+  }
+
+  const matches = (listBody as GistSummary[])
+    .filter((g) => g && typeof g === 'object' && opts.expected_filename in (g.files ?? {}))
+    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+
+  const match = matches[0];
+  if (!match) {
+    throw new PassportsignError(
+      'gist_not_found',
+      `no public gist owned by '${opts.username}' contains file '${opts.expected_filename}'`,
+    );
+  }
+
+  // Step 2: re-fetch the gist by id to get the full content.
+  let detailResponse: Response;
+  try {
+    detailResponse = await fetchImpl(`${baseUrl}/gists/${match.id}`, { headers });
+  } catch (err) {
+    throw new PassportsignError(
+      'internal_error',
+      `GitHub get-gist request failed: ${err instanceof Error ? err.message : String(err)}`,
+      err,
+    );
+  }
+  if (!detailResponse.ok) {
+    throw new PassportsignError(
+      'internal_error',
+      `GitHub get-gist returned HTTP ${detailResponse.status}`,
+    );
+  }
+
+  let detail: GistSummary;
+  try {
+    detail = (await detailResponse.json()) as GistSummary;
+  } catch (err) {
+    throw new PassportsignError('internal_error', 'GitHub get-gist returned non-JSON', err);
+  }
+
+  // Step 3: owner check (case-insensitive per spec §10 row 7).
+  const ownerLogin = detail.owner?.login;
+  if (!ownerLogin || ownerLogin.toLowerCase() !== opts.username.toLowerCase()) {
+    throw new PassportsignError(
+      'gist_wrong_owner',
+      `gist ${match.id} owner '${ownerLogin ?? 'unknown'}' does not match expected '${opts.username}'`,
+    );
+  }
+
+  // Step 4: content exact match.
+  const file = (detail.files ?? {})[opts.expected_filename];
+  const content = file?.content;
+  if (typeof content !== 'string') {
+    throw new PassportsignError(
+      'gist_wrong_content',
+      `gist ${match.id} has no readable content for '${opts.expected_filename}'`,
+    );
+  }
+  if (content !== opts.expected_content) {
+    throw new PassportsignError(
+      'gist_wrong_content',
+      `gist ${match.id} content does not exactly match the expected nonce`,
+    );
+  }
+
+  // Step 5: freshness — gist's updated_at must be at/after init.
+  const updatedAtMs = Date.parse(detail.updated_at);
+  if (Number.isNaN(updatedAtMs)) {
+    throw new PassportsignError(
+      'internal_error',
+      `gist ${match.id} updated_at is unparseable: ${detail.updated_at}`,
+    );
+  }
+  if (updatedAtMs < opts.not_before.getTime()) {
+    throw new PassportsignError(
+      'gist_predates_init',
+      `gist ${match.id} updated_at (${detail.updated_at}) predates init (${opts.not_before.toISOString()})`,
+    );
+  }
+
+  return {
+    url: detail.html_url,
+    content_sha256: sha256Hex(content),
+    updated_at: detail.updated_at,
+  };
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+/**
+ * Public API of @passportsign/core.
+ *
+ * Day 1-2: canonical JCS + in-toto statement + bundle format.
+ * Day 3-4: §4 error vocabulary + nonce + GitHub gist check +
+ *          SQLite cache + bind orchestrator (no Rekor yet).
+ */
+
+export {
+  canonicalize,
+  canonicalSha256Hex,
+} from './canonical.js';
+
+export {
+  IN_TOTO_STATEMENT_TYPE,
+  PASSPORTSIGN_PREDICATE_TYPE,
+  buildStatement,
+  type BuildStatementInput,
+  type DisclosureLevel,
+  type PassportsignPredicate,
+  type PassportsignStatement,
+} from './statement.js';
+
+export {
+  BUNDLE_FORMAT_VERSION,
+  BundleValidationError,
+  readBundle,
+  validateBundle,
+  writeBundle,
+  type PassportsignBundle,
+  type RekorBundleFields,
+} from './bundle.js';
+
+export {
+  ERROR_CODES,
+  PassportsignError,
+  type ErrorCode,
+} from './errors.js';
+
+export {
+  NONCE_BYTES,
+  NONCE_BASE32_LENGTH,
+  base32Encode,
+  generateNonce,
+} from './nonce.js';
+
+export {
+  checkGistControl,
+  type CheckGistOptions,
+  type GistEvidence,
+} from './github.js';
+
+// SQLite cache is intentionally not re-exported from the main entry —
+// `node:sqlite` doesn't bundle cleanly (esbuild strips the `node:` prefix
+// and there's no public `sqlite` npm package by that name). Consumers
+// who need it should import from `@passportsign/core/storage/sqlite`
+// directly. The v0 CLI doesn't use the cache; rebuild is v1 work.
+
+export {
+  prepareBinding,
+  type PrepareBindingDeps,
+  type PrepareBindingInit,
+  type PrepareBindingInput,
+  type PreparedBinding,
+} from './bind.js';
+
+export {
+  DSSE_VERSION,
+  IN_TOTO_PAYLOAD_TYPE,
+  pae,
+  signEnvelope,
+  type DsseEnvelope,
+  type DsseSignature,
+  type SignEnvelopeResult,
+} from './dsse.js';
+
+export {
+  DEFAULT_REKOR_BASE_URL,
+  PublicSigstoreRekorClient,
+  buildIntotoEntryBody,
+  type InclusionProof,
+  type PublicSigstoreRekorClientOptions,
+  type RekorClient,
+  type RekorEntryResponse,
+} from './log/rekor.js';
+
+export {
+  submitBinding,
+  type SubmitBindingDeps,
+  type SubmitBindingResult,
+} from './submit.js';
+
+export {
+  hashLeaf,
+  hashPair,
+  verifyConsistency,
+  verifyInclusion,
+} from './merkle.js';
+
+export {
+  packSdkPayload,
+  unpackSdkPayload,
+  type PackedSdkPayload,
+  type SdkPayload,
+} from './sdk-payload.js';
+
+export {
+  renderBadgeMarkdown,
+  renderBadgeSvg,
+  type BadgeInput,
+} from './badge.js';
+
+export {
+  verifyBundle,
+  type BundleVerifyResult,
+  type CheckResult,
+  type SdkVerifier,
+  type SdkVerifyInput,
+  type SdkVerifyResult,
+  type VerifyBundleDeps,
+} from './verifier.js';