sello 0.1.1 → 0.1.2

package/dist/cose/protected-header.js

@@ -0,0 +1,210 @@
+import {                               decodeCbor, encodeCbor } from "../cbor.js";
+import { assertTokenRef } from "../crypto/identifiers.js";
+import {
+                       
+  assertCanonicalLogUrl,
+} from "../log/canonical-url.js";
+
+export const COSE_ALG_LABEL = 1;
+export const COSE_CRIT_LABEL = 2;
+export const COSE_KID_LABEL = 4;
+export const SELLO_VERSION_LABEL = -65537;
+export const SELLO_TOKEN_REF_LABEL = -65538;
+export const SELLO_LOG_URL_LABEL = -65539;
+
+export const COSE_ALG_EDDSA = -8;
+export const SELLO_VERSION = "0.1.0";
+
+                               
+                              
+                  
+                           
+                                       
+                              
+                                 
+  
+
+                                              
+       
+                    
+                                                                         
+   
+   
+                                   
+                               
+                            
+    
+
+const UNDERSTOOD_LABELS = new Set([
+  COSE_ALG_LABEL,
+  COSE_CRIT_LABEL,
+  COSE_KID_LABEL,
+  SELLO_VERSION_LABEL,
+  SELLO_TOKEN_REF_LABEL,
+  SELLO_LOG_URL_LABEL,
+]);
+
+export function encodeProtectedHeader(header                 )             {
+  validateProtectedHeaderInput(header);
+
+  const map          = new Map([
+    [COSE_ALG_LABEL, header.alg ?? COSE_ALG_EDDSA],
+    [COSE_KID_LABEL, header.kid],
+    [SELLO_VERSION_LABEL, header.sello_version ?? SELLO_VERSION],
+    [SELLO_TOKEN_REF_LABEL, header.sello_token_ref],
+    [SELLO_LOG_URL_LABEL, header.sello_log_url],
+  ]);
+
+  if (header.crit !== undefined) {
+    map.set(COSE_CRIT_LABEL, [...header.crit]);
+  }
+
+  return encodeCbor(map);
+}
+
+export function decodeProtectedHeader(bytes            )                         {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError("protected header bytes must be a Uint8Array");
+  }
+
+  const decoded = decodeCbor(bytes);
+  if (!(decoded instanceof Map)) {
+    throw new TypeError("protected header must be a CBOR map");
+  }
+
+  const alg = readRequired(decoded, COSE_ALG_LABEL, "alg");
+  if (alg !== COSE_ALG_EDDSA) {
+    throw new TypeError("protected header alg must be -8");
+  }
+
+  const kid = readRequired(decoded, COSE_KID_LABEL, "kid");
+  assertKid(kid);
+
+  const selloVersion = readRequired(
+    decoded,
+    SELLO_VERSION_LABEL,
+    "sello_version",
+  );
+  if (selloVersion !== SELLO_VERSION) {
+    throw new TypeError(`protected header sello_version must be ${SELLO_VERSION}`);
+  }
+
+  const selloTokenRef = readRequired(
+    decoded,
+    SELLO_TOKEN_REF_LABEL,
+    "sello_token_ref",
+  );
+  assertTokenRef(selloTokenRef, "protected header sello_token_ref");
+
+  const selloLogUrl = readRequired(decoded, SELLO_LOG_URL_LABEL, "sello_log_url");
+  assertCanonicalLogUrl(selloLogUrl, "protected header sello_log_url");
+
+  const crit = readCrit(decoded.get(COSE_CRIT_LABEL));
+  const unknownHeaders = collectUnknownHeaders(decoded);
+
+  return {
+    alg,
+    kid: copyBytes(kid),
+    ...(crit === undefined ? {} : { crit }),
+    sello_version: selloVersion,
+    sello_token_ref: copyBytes(selloTokenRef),
+    sello_log_url: selloLogUrl,
+    protectedBytes: copyBytes(bytes),
+    unknownHeaders,
+  };
+}
+
+function validateProtectedHeaderInput(header                 )       {
+  if (typeof header !== "object" || header === null) {
+    throw new TypeError("protected header must be an object");
+  }
+
+  if (header.alg !== undefined && header.alg !== COSE_ALG_EDDSA) {
+    throw new TypeError("protected header alg must be -8");
+  }
+
+  assertKid(header.kid);
+
+  if (
+    header.sello_version !== undefined &&
+    header.sello_version !== SELLO_VERSION
+  ) {
+    throw new TypeError(`protected header sello_version must be ${SELLO_VERSION}`);
+  }
+
+  assertTokenRef(header.sello_token_ref, "protected header sello_token_ref");
+  assertCanonicalLogUrl(header.sello_log_url, "protected header sello_log_url");
+  readCrit(header.crit);
+}
+
+function readRequired(
+  map         ,
+  label        ,
+  name        ,
+)            {
+  if (!map.has(label)) {
+    throw new TypeError(`protected header is missing ${name}`);
+  }
+
+  return map.get(label)             ;
+}
+
+function readCrit(value                       )                       {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new TypeError("protected header crit must be an array");
+  }
+
+  if (value.length === 0) {
+    throw new TypeError("protected header crit must not be empty");
+  }
+
+  const seen = new Set        ();
+  const out           = [];
+
+  for (const label of value) {
+    if (!Number.isSafeInteger(label)) {
+      throw new TypeError("protected header crit labels must be integers");
+    }
+
+    if (seen.has(label)) {
+      throw new TypeError("protected header crit must not contain duplicates");
+    }
+
+    if (!UNDERSTOOD_LABELS.has(label)) {
+      throw new TypeError(`unknown critical protected header label ${label}`);
+    }
+
+    seen.add(label);
+    out.push(label);
+  }
+
+  return out;
+}
+
+function assertKid(value         )                              {
+  if (!(value instanceof Uint8Array) || value.byteLength === 0) {
+    throw new TypeError("protected header kid must be non-empty bytes");
+  }
+}
+
+function collectUnknownHeaders(map         )          {
+  const unknownHeaders          = new Map();
+
+  for (const [label, value] of map) {
+    if (typeof label === "number" && UNDERSTOOD_LABELS.has(label)) {
+      continue;
+    }
+
+    unknownHeaders.set(label, value);
+  }
+
+  return unknownHeaders;
+}
+
+function copyBytes(value            )             {
+  return new Uint8Array(value);
+}

package/dist/cose/sign1.js

@@ -0,0 +1,124 @@
+import {                               decodeCbor, encodeCbor } from "../cbor.js";
+import {
+  assertEd25519PrivateKey,
+  assertEd25519PublicKey,
+  assertEd25519Signature,
+  generateEd25519KeyPair,
+  signEd25519,
+  verifyEd25519Signature,
+                      
+} from "../crypto/ed25519.js";
+import { decodeProtectedHeader } from "./protected-header.js";
+
+export { generateEd25519KeyPair,                     };
+
+                               
+                             
+                      
+                        
+  
+
+                                        
+                                   
+                      
+                                
+  
+
+                                          
+                       
+                               
+  
+
+const EMPTY = new Uint8Array();
+
+export function signReceiptEnvelope(input                          )             {
+  assertBytes(input.protectedHeaderBytes, "protectedHeaderBytes");
+  assertBytes(input.payload, "payload");
+  assertEd25519PrivateKey(input.servicePrivateKey, "servicePrivateKey");
+  decodeProtectedHeader(input.protectedHeaderBytes);
+
+  const signature = signEd25519(
+    buildSigStructure(input.protectedHeaderBytes, input.payload),
+    input.servicePrivateKey,
+  );
+
+  return encodeCbor([
+    input.protectedHeaderBytes,
+    new Map(),
+    input.payload,
+    signature,
+  ]);
+}
+
+export function verifyReceiptEnvelope(
+  input                            ,
+)                  {
+  assertBytes(input.envelope, "envelope");
+  assertEd25519PublicKey(input.servicePublicKey, "servicePublicKey");
+
+  const decoded = decodeReceiptEnvelope(input.envelope);
+  decodeProtectedHeader(decoded.protectedBytes);
+
+  const ok = verifyEd25519Signature(
+    buildSigStructure(decoded.protectedBytes, decoded.payload),
+    decoded.signature,
+    input.servicePublicKey,
+  );
+
+  if (!ok) {
+    throw new TypeError("COSE_Sign1 signature verification failed");
+  }
+
+  return decoded;
+}
+
+export function decodeReceiptEnvelope(envelope            )                  {
+  const decoded = decodeCbor(envelope);
+
+  if (!Array.isArray(decoded) || decoded.length !== 4) {
+    throw new TypeError("COSE_Sign1 envelope must be a 4-element array");
+  }
+
+  const [protectedBytes, unprotected, payload, signature] = decoded;
+
+  assertBytes(protectedBytes, "COSE_Sign1 protected header");
+  assertEmptyUnprotected(unprotected);
+  assertBytes(payload, "COSE_Sign1 payload");
+  assertEd25519Signature(signature, "COSE_Sign1 signature");
+
+  return {
+    protectedBytes: copyBytes(protectedBytes),
+    payload: copyBytes(payload),
+    signature: copyBytes(signature),
+  };
+}
+
+export function buildSigStructure(
+  protectedHeaderBytes            ,
+  payload            ,
+)             {
+  assertBytes(protectedHeaderBytes, "protectedHeaderBytes");
+  assertBytes(payload, "payload");
+
+  return encodeCbor(["Signature1", protectedHeaderBytes, EMPTY, payload]);
+}
+
+function assertEmptyUnprotected(value           )                           {
+  if (!(value instanceof Map)) {
+    throw new TypeError("COSE_Sign1 unprotected header must be a map");
+  }
+
+  if (value.size !== 0) {
+    throw new TypeError("COSE_Sign1 unprotected header must be empty");
+  }
+}
+
+function assertBytes(value         , name        )                              {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}
+
+function copyBytes(value            )             {
+  return new Uint8Array(value);
+}

package/dist/crypto/ed25519.js

@@ -0,0 +1,117 @@
+import {
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign,
+  verify,
+} from "node:crypto";
+
+import { concat } from "../cbor.js";
+
+                              
+                        
+                         
+  
+
+export const ED25519_KEY_LENGTH = 32;
+export const ED25519_SIGNATURE_LENGTH = 64;
+
+const ED25519_PUBLIC_KEY_SPKI_PREFIX = hex("302a300506032b6570032100");
+const ED25519_PRIVATE_KEY_PKCS8_PREFIX = hex("302e020100300506032b657004220420");
+
+export function generateEd25519KeyPair()                 {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+
+  return {
+    publicKey: exportRawEd25519PublicKey(publicKey),
+    privateKey: exportRawEd25519PrivateKey(privateKey),
+  };
+}
+
+export function signEd25519(message            , privateKey            )             {
+  assertBytes(message, "message");
+  assertEd25519PrivateKey(privateKey, "privateKey");
+
+  return new Uint8Array(sign(null, message, createEd25519PrivateKey(privateKey)));
+}
+
+export function verifyEd25519Signature(
+  message            ,
+  signature            ,
+  publicKey            ,
+)          {
+  assertBytes(message, "message");
+  assertEd25519Signature(signature, "signature");
+  assertEd25519PublicKey(publicKey, "publicKey");
+
+  return verify(null, message, createEd25519PublicKey(publicKey), signature);
+}
+
+export function assertEd25519PublicKey(
+  value         ,
+  name = "publicKey",
+)                              {
+  assertByteLength(value, ED25519_KEY_LENGTH, name);
+}
+
+export function assertEd25519PrivateKey(
+  value         ,
+  name = "privateKey",
+)                              {
+  assertByteLength(value, ED25519_KEY_LENGTH, name);
+}
+
+export function assertEd25519Signature(
+  value         ,
+  name = "signature",
+)                              {
+  assertByteLength(value, ED25519_SIGNATURE_LENGTH, name);
+}
+
+function createEd25519PublicKey(rawPublicKey            )                                     {
+  assertEd25519PublicKey(rawPublicKey, "rawPublicKey");
+  return createPublicKey({
+    key: Buffer.from(concat([ED25519_PUBLIC_KEY_SPKI_PREFIX, rawPublicKey])),
+    format: "der",
+    type: "spki",
+  });
+}
+
+function createEd25519PrivateKey(rawPrivateKey            )                                      {
+  assertEd25519PrivateKey(rawPrivateKey, "rawPrivateKey");
+  return createPrivateKey({
+    key: Buffer.from(concat([ED25519_PRIVATE_KEY_PKCS8_PREFIX, rawPrivateKey])),
+    format: "der",
+    type: "pkcs8",
+  });
+}
+
+function exportRawEd25519PublicKey(key                                    )             {
+  const der = new Uint8Array(key.export({ format: "der", type: "spki" }));
+  return new Uint8Array(der.subarray(der.byteLength - ED25519_KEY_LENGTH));
+}
+
+function exportRawEd25519PrivateKey(key                                     )             {
+  const der = new Uint8Array(key.export({ format: "der", type: "pkcs8" }));
+  return new Uint8Array(der.subarray(der.byteLength - ED25519_KEY_LENGTH));
+}
+
+function assertByteLength(
+  value         ,
+  length        ,
+  name        ,
+)                              {
+  if (!(value instanceof Uint8Array) || value.byteLength !== length) {
+    throw new TypeError(`${name} must be a ${length}-byte Uint8Array`);
+  }
+}
+
+function assertBytes(value         , name        )                              {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}
+
+function hex(value        )             {
+  return Uint8Array.from(Buffer.from(value, "hex"));
+}

package/dist/crypto/identifiers.js

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+
+export const SHA256_DIGEST_LENGTH = 32;
+export const AGENT_IDENTIFIER_HEX_LENGTH = 32;
+
+                                
+                              
+                           
+  
+
+export function sha256(bytes            )             {
+  assertUint8Array(bytes, "bytes");
+  return new Uint8Array(createHash("sha256").update(bytes).digest());
+}
+
+export function deriveTokenIdentifiers(
+  authorizationTokenBytes            ,
+)                   {
+  assertUint8Array(authorizationTokenBytes, "authorizationTokenBytes");
+
+  const digest = sha256(authorizationTokenBytes);
+
+  return {
+    sello_token_ref: digest,
+    agent_identifier: toHex(digest.subarray(0, 16)),
+  };
+}
+
+export function isTokenRef(value         )                      {
+  return value instanceof Uint8Array && value.byteLength === SHA256_DIGEST_LENGTH;
+}
+
+export function assertTokenRef(value         , name = "sello_token_ref")       {
+  if (!isTokenRef(value)) {
+    throw new TypeError(`${name} must be a 32-byte Uint8Array`);
+  }
+}
+
+export function isAgentIdentifier(value         )                  {
+  return (
+    typeof value === "string" &&
+    /^[0-9a-f]{32}$/.test(value)
+  );
+}
+
+export function assertAgentIdentifier(
+  value         ,
+  name = "agent_identifier",
+)       {
+  if (!isAgentIdentifier(value)) {
+    throw new TypeError(`${name} must be a 32-character lowercase hex string`);
+  }
+}
+
+export function toHex(bytes            )         {
+  assertUint8Array(bytes, "bytes");
+  return Buffer.from(bytes).toString("hex");
+}
+
+function assertUint8Array(value         , name        )                              {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+}