sello 0.1.0 → 0.1.2

package/dist/sdk/service.js

@@ -0,0 +1,561 @@
+import {                    buildReceipt } from "../service/create-receipt.js";
+import { verifySelloJwsToken } from "../token/jws-profile.js";
+import {                       assertCanonicalLogUrl, logUrlsEqual } from "../log/canonical-url.js";
+import { canonicalJsonBytes } from "../mcp/middleware.js";
+import {
+                
+                       
+  decodeBase64url,
+  normalizeEd25519PublicKey,
+  normalizeServiceKey,
+} from "./keys.js";
+import {                        http } from "./logs.js";
+import {
+  BackgroundReceiptPublisher,
+                 
+                          
+                  
+} from "./publisher.js";
+
+                                                   
+                   
+                                  
+
+                                                
+         
+                                  
+
+                                                     
+                             
+                        
+                      
+                  
+  
+
+                                                   
+                                                                        
+                                                       
+                                                          
+                                                     
+                                                              
+                                                                      
+  
+
+                                  
+                   
+                               
+                        
+                                                                      
+                                  
+                           
+                         
+                                        
+                                           
+                     
+                                                 
+                                           
+                                      
+  
+
+                                                            
+
+                             
+                          
+                       
+                                                 
+                                                  
+                                         
+                         
+  
+
+                                                      
+
+                        
+                                                 
+                                                              
+
+                              
+                  
+                         
+                                
+                                 
+                        
+                                        
+                    
+                                                 
+  
+
+                     
+                                                       
+     
+                     
+                        
+                        
+                        
+                                                     
+      
+
+export function createSelloService(input                    )                {
+  const deferred = resolveDeferredConfig(input, process.env);
+  const publisherOptions = resolvePublisherOptions(input, process.env);
+  let loaded                                            ;
+  let publisher                                        ;
+
+  async function config()                                 {
+    loaded ??= loadDeferredConfig(deferred);
+    return await loaded;
+  }
+
+  function publisherFor(resolved                       )                             {
+    publisher ??= new BackgroundReceiptPublisher({
+      log: resolved.log,
+      ...publisherOptions,
+    });
+    return publisher;
+  }
+
+  return {
+    tool                   (
+      actionType        ,
+      handler                                     ,
+      options                                      = {},
+    )                                      {
+      if (typeof actionType !== "string" || actionType.length === 0) {
+        throw new TypeError("Sello action type must be a non-empty string");
+      }
+
+      return async (request         )                    => {
+        const resolved = await config();
+        const authorizationToken = resolveValue(
+          options.authorizationToken ?? defaultAuthorizationToken,
+          request,
+        );
+        const tokenIssuerPublicKey = await resolveTokenIssuerPublicKey(resolved.tokenIssuer);
+        const verifiedToken = verifySelloJwsToken({
+          authorizationToken,
+          issuerPublicKey: tokenIssuerPublicKey,
+        });
+        const selloLogs = selectSelloLogs(
+          verifiedToken.selloLogs,
+          resolved.fallbackSelloLogs,
+          resolved.log.logUrl,
+        );
+        const base = {
+          authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
+          ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
+          selloLogs,
+          serviceKid: resolved.serviceKid,
+          servicePrivateKey: resolved.servicePrivateKey,
+          serviceIdentifier: resolved.service,
+          logUrl: resolved.log.logUrl,
+          actionType,
+          actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
+          timestamp: resolved.now(),
+        };
+
+        if (options.isDenied && (await options.isDenied(request))) {
+          const response = options.deniedResponse
+            ? await options.deniedResponse(request)
+            : undefined;
+          const receipt = emitReceipt({
+            ...base,
+            actionOutputBytes: new Uint8Array(),
+            resultStatus: "denied",
+          });
+          resolved.onReceipt?.({ resultStatus: "denied", receipt, response });
+          await submit(resolved, receipt, base.timestamp);
+
+          if (options.deniedResponse) {
+            return response            ;
+          }
+
+          throw new SelloDeniedError(receipt);
+        }
+
+        let response          ;
+        try {
+          response = await handler(request);
+        } catch (error) {
+          const receipt = emitReceipt({
+            ...base,
+            actionOutputBytes: (options.canonicalizeError ?? canonicalErrorBytes)(
+              error,
+            ),
+            resultStatus: "error",
+          });
+          resolved.onReceipt?.({ resultStatus: "error", receipt, error });
+          await submit(resolved, receipt, base.timestamp);
+          throw error;
+        }
+
+        const receipt = emitReceipt({
+          ...base,
+          actionOutputBytes: (options.canonicalizeOutput ?? canonicalJsonBytes)(
+            response,
+          ),
+          resultStatus: "success",
+        });
+        resolved.onReceipt?.({ resultStatus: "success", receipt, response });
+        await submit(resolved, receipt, base.timestamp);
+        return response;
+      };
+    },
+    async flush()                {
+      await publisher?.flush();
+    },
+  };
+
+  async function submit(
+    resolved                       ,
+    receipt              ,
+    integratedTime        ,
+  )                {
+    const currentPublisher = publisherFor(resolved);
+    if (currentPublisher.mode === "await") {
+      await currentPublisher.publish({
+        envelope: receipt.envelope,
+        integratedTime,
+      });
+      return;
+    }
+
+    currentPublisher.publishBackground({
+      envelope: receipt.envelope,
+      integratedTime,
+    });
+  }
+}
+
+export class SelloDeniedError extends Error {
+           receipt              ;
+
+  constructor(receipt              ) {
+    super("Sello request denied");
+    this.name = "SelloDeniedError";
+    this.receipt = receipt;
+  }
+}
+
+function emitReceipt(input                                    )               {
+  return buildReceipt(input);
+}
+
+function resolveDeferredConfig(
+  input                               ,
+  env             ,
+)                 {
+  const objectInput =
+    typeof input === "object" && input !== null ? input : {};
+  const serviceOverride = typeof input === "string" ? input : objectInput.service;
+  const hostedSecret = env.SELLO_SECRET_KEY;
+
+  if (
+    hostedSecret &&
+    objectInput.serviceKey === undefined &&
+    env.SELLO_SERVICE_KEY === undefined
+  ) {
+    return {
+      type: "hosted",
+      secretKey: hostedSecret,
+      configUrl:
+        env.SELLO_HOSTED_CONFIG_URL ?? "https://sello.build/api/sdk/config",
+      now: objectInput.now ?? nowUtcSeconds,
+      onReceipt: objectInput.onReceipt,
+    };
+  }
+
+  return {
+    type: "resolved",
+    config: resolveSelfHostedConfig(objectInput, serviceOverride, env),
+  };
+}
+
+function resolvePublisherOptions(
+  input                               ,
+  env             ,
+)                                                                           {
+  const objectInput =
+    typeof input === "object" && input !== null ? input : {};
+
+  return {
+    submit: objectInput.submit ?? envSubmitMode(env),
+    onSubmitError: objectInput.onSubmitError,
+    onDrop: objectInput.onDrop,
+  };
+}
+
+function resolveSelfHostedConfig(
+  input                    ,
+  serviceOverride                    ,
+  env             ,
+)                        {
+  const service = serviceOverride ?? env.SELLO_SERVICE_ID;
+  if (!service) {
+    throw new TypeError(
+      "Sello setup missing SELLO_SERVICE_ID. Set SELLO_SERVICE_ID or call sello.service(\"service-id\").",
+    );
+  }
+
+  const serviceKey = normalizeServiceKey(
+    input.serviceKey ?? env.SELLO_SERVICE_KEY,
+    input.serviceKid ?? env.SELLO_SERVICE_KID,
+  );
+  const log =
+    input.log ??
+    (env.SELLO_LOG_URL
+      ? http(env.SELLO_LOG_URL, { endpoint: env.SELLO_LOG_ENDPOINT })
+      : undefined);
+
+  if (!log) {
+    throw new TypeError(
+      "Sello setup missing SELLO_LOG_URL. Set SELLO_LOG_URL or pass log explicitly.",
+    );
+  }
+
+  return {
+    service,
+    serviceKid: serviceKey.kid,
+    servicePrivateKey: serviceKey.privateKey,
+    tokenIssuer: normalizeTokenIssuer(input, env),
+    log,
+    fallbackSelloLogs: input.fallbackSelloLogs ?? [log.logUrl],
+    now: input.now ?? nowUtcSeconds,
+    onReceipt: input.onReceipt,
+  };
+}
+
+async function loadDeferredConfig(
+  deferred                ,
+)                                 {
+  if (deferred.type === "resolved") {
+    return deferred.config;
+  }
+
+  const response = await fetch(deferred.configUrl, {
+    method: "GET",
+    headers: {
+      authorization: `Bearer ${deferred.secretKey}`,
+    },
+  });
+
+  if (!response.ok) {
+    throw new TypeError(`sello.build config fetch failed with HTTP ${response.status}`);
+  }
+
+  const config = await response.json();
+  if (!isRecord(config)) {
+    throw new TypeError("sello.build config response must be an object");
+  }
+
+  const service = readString(config.service, "hosted service");
+  const logUrl = readString(config.logUrl, "hosted logUrl");
+  const hostedServiceKey = normalizeServiceKey(
+    readString(config.serviceKey, "hosted serviceKey"),
+  );
+
+  return {
+    service,
+    serviceKid: hostedServiceKey.kid,
+    servicePrivateKey: hostedServiceKey.privateKey,
+    tokenIssuer: {
+      type: "public-key",
+      publicKey: normalizeEd25519PublicKey(
+        readString(config.tokenIssuerPublicKey, "hosted tokenIssuerPublicKey"),
+        "hosted tokenIssuerPublicKey",
+      ),
+    },
+    log: http(logUrl, {
+      endpoint:
+        typeof config.logEndpoint === "string" ? config.logEndpoint : undefined,
+    }),
+    fallbackSelloLogs: [http(logUrl).logUrl],
+    now: deferred.now,
+    onReceipt: deferred.onReceipt,
+  };
+}
+
+function normalizeTokenIssuer(
+  input                    ,
+  env             ,
+)                    {
+  const tokenIssuer = input.tokenIssuer;
+
+  if (tokenIssuer instanceof Uint8Array || typeof tokenIssuer === "string") {
+    return {
+      type: "public-key",
+      publicKey: normalizeEd25519PublicKey(tokenIssuer, "tokenIssuer"),
+    };
+  }
+
+  if (tokenIssuer && typeof tokenIssuer === "object") {
+    if (tokenIssuer.publicKey) {
+      return {
+        type: "public-key",
+        publicKey: normalizeEd25519PublicKey(
+          tokenIssuer.publicKey,
+          "tokenIssuer.publicKey",
+        ),
+      };
+    }
+
+    if (tokenIssuer.jwksUrl) {
+      return { type: "jwks", jwksUrl: tokenIssuer.jwksUrl };
+    }
+  }
+
+  if (input.tokenIssuerPublicKey || env.SELLO_TOKEN_ISSUER_PUBLIC_KEY) {
+    return {
+      type: "public-key",
+      publicKey: normalizeEd25519PublicKey(
+        input.tokenIssuerPublicKey ?? env.SELLO_TOKEN_ISSUER_PUBLIC_KEY          ,
+        "SELLO_TOKEN_ISSUER_PUBLIC_KEY",
+      ),
+    };
+  }
+
+  const jwksUrl = input.tokenIssuerJwks ?? env.SELLO_TOKEN_ISSUER_JWKS;
+  if (jwksUrl) {
+    return { type: "jwks", jwksUrl };
+  }
+
+  throw new TypeError(
+    "Sello setup missing token issuer. Set SELLO_TOKEN_ISSUER_PUBLIC_KEY, SELLO_TOKEN_ISSUER_JWKS, or pass tokenIssuer.",
+  );
+}
+
+async function resolveTokenIssuerPublicKey(
+  issuer                   ,
+)                      {
+  if (issuer.type === "public-key") {
+    return issuer.publicKey;
+  }
+
+  issuer.publicKey ??= await fetchEd25519JwksKey(issuer.jwksUrl);
+  return issuer.publicKey;
+}
+
+async function fetchEd25519JwksKey(jwksUrl        )                      {
+  const response = await fetch(jwksUrl);
+  if (!response.ok) {
+    throw new TypeError(`token issuer JWKS fetch failed with HTTP ${response.status}`);
+  }
+
+  const jwks = await response.json();
+  if (!isRecord(jwks) || !Array.isArray(jwks.keys)) {
+    throw new TypeError("token issuer JWKS must contain keys");
+  }
+
+  const key = jwks.keys.find(
+    (candidate) =>
+      isRecord(candidate) &&
+      candidate.kty === "OKP" &&
+      candidate.crv === "Ed25519" &&
+      typeof candidate.x === "string",
+  );
+
+  if (!key || !isRecord(key) || typeof key.x !== "string") {
+    throw new TypeError("token issuer JWKS must contain an Ed25519 OKP key");
+  }
+
+  return normalizeEd25519PublicKey(decodeBase64url(key.x, "JWKS x"), "JWKS x");
+}
+
+function selectSelloLogs(
+  tokenLogs                               ,
+  fallbackLogs                               ,
+  logUrl                 ,
+)                    {
+  const selloLogs = tokenLogs ?? fallbackLogs ?? [];
+  if (selloLogs.length === 0) {
+    throw new TypeError("Sello token did not provide owner-trusted logs");
+  }
+
+  for (const entry of selloLogs) {
+    assertCanonicalLogUrl(entry, "sello_logs entry");
+    if (logUrlsEqual(entry, logUrl)) {
+      return selloLogs;
+    }
+  }
+
+  throw new TypeError("Sello log must be listed in the token's sello_logs");
+}
+
+function defaultAuthorizationToken(request         )                      {
+  if (isRecord(request)) {
+    const direct = request.authorizationToken ?? request.authorization;
+    if (typeof direct === "string" || direct instanceof Uint8Array) {
+      return stripBearer(direct);
+    }
+
+    const headers = request.headers;
+    if (isRecord(headers)) {
+      const header = headers.authorization ?? headers.Authorization;
+      if (typeof header === "string") {
+        return stripBearer(header);
+      }
+    }
+  }
+
+  throw new TypeError(
+    "Sello authorization token not found. Pass authorizationToken or include request.authorizationToken.",
+  );
+}
+
+function stripBearer(value                     )                      {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  return value.startsWith("Bearer ") ? value.slice("Bearer ".length) : value;
+}
+
+function canonicalErrorBytes(error         )             {
+  if (error instanceof Error) {
+    return canonicalJsonBytes({
+      name: error.name,
+      message: error.message,
+    });
+  }
+
+  return canonicalJsonBytes({ error: String(error) });
+}
+
+function resolveValue                (
+  value                                    ,
+  request         ,
+)        {
+  if (typeof value === "function") {
+    return (value                               )(request);
+  }
+
+  return value;
+}
+
+function envSubmitMode(env             )                                              {
+  const mode = env.SELLO_SUBMIT_MODE;
+  if (mode === undefined) {
+    return undefined;
+  }
+
+  if (mode !== "background" && mode !== "await") {
+    throw new TypeError("SELLO_SUBMIT_MODE must be background or await");
+  }
+
+  return mode;
+}
+
+function nowUtcSeconds()         {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function isRecord(value         )                                   {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readString(value         , name        )         {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+
+  return value;
+}