@blamejs/core 0.8.43 → 0.8.49

package/lib/auth-header.js

@@ -1,36 +1,41 @@
 "use strict";
 /**
- * auth-header — construct HTTP Authorization headers for the framework's
- * outbound consumers.
+ * @module b.authHeader
+ * @nav    HTTP
+ * @title  Auth Headers
  *
- * The previous shape was `_authHeaders(config)` reimplemented in three
- * places (log-stream-webhook, object-store-http-put, object-store-gcs).
- * Each handled the same { auth, token, username, password } shape with
- * subtly different argument names and case semantics. This module
- * collapses the construction.
+ * @intro
+ *   RFC 7235 / RFC 7617 outbound Authorization header construction —
+ *   the small, security-aware primitive every framework consumer that
+ *   talks to a credentialed HTTP endpoint composes (log-stream-webhook,
+ *   object-store-http-put, object-store-gcs, custom outbound clients).
  *
- * Public API:
+ *   Previously each consumer re-implemented `_authHeaders(config)` with
+ *   subtly different argument names and case semantics. This module
+ *   collapses the construction so token / credential rules live in one
+ *   place: never produce `Basic <b64('undefined:...')>`, always pass
+ *   bearer tokens through unmodified, refuse unknown auth methods at
+ *   call time rather than silently emitting no header.
  *
- *   bearer(token)                      → { Authorization: "Bearer <token>" }
- *   basic(username, password)          → { Authorization: "Basic <b64>" }
- *   fromConfig({ auth, token, ... })   → headers object for the named auth method
+ *   Three forms:
+ *     - `bearer(token)`               -> { Authorization: "Bearer <token>" }
+ *     - `basic(username, password)`   -> { Authorization: "Basic <b64>" }
+ *     - `fromConfig({ auth, ... })`   -> dispatch by `auth` field
  *
- * fromConfig accepts:
+ *   `fromConfig` accepts `{ auth: "none" }` (returns `{}`),
+ *   `{ auth: "bearer", token }`, and `{ auth: "basic", username,
+ *   password }`. Anything else throws `AuthHeaderError`. The "raw
+ *   header pass-through" mode some consumers wanted is intentionally
+ *   NOT this module's job — that's plain header merging at the call
+ *   site, kept separate so the auth-header primitive stays pure
+ *   string construction with no I/O.
  *
- *   { auth: "none" }                                → {}
- *   { auth: "bearer", token }                       → bearer(token)
- *   { auth: "basic",  username, password }          → basic(username, password)
+ *   Validation tier: config-time / entry-point. Bad opts throw
+ *   synchronously so an operator catches the typo at boot rather than
+ *   on the first outbound request.
  *
- * Anything else throws AuthHeaderError. The "header" pass-through mode
- * that consumers used to wedge into _authHeaders is NOT auth-header's job
- * — that's just header merging. Consumers do `Object.assign({}, config.headers)`
- * themselves and combine the two layers at the call site.
- *
- * Why this is a separate primitive vs. a helper inside http-client:
- *   - Some callers (log-stream-local) might emit auth headers without
- *     going through http-client (e.g. signed-URL inputs to a token).
- *   - Keeping it pure-string-construction with no I/O makes it test-only
- *     in 0ms and reusable from non-network contexts.
+ * @card
+ *   RFC 7235 / RFC 7617 outbound Authorization header construction — the small, security-aware primitive every framework consumer that talks to a credentialed HTTP endpoint composes (log-stream-webhook, object-store-http-put, object-store-gcs, custom outbound clients).
  */
 
 var { FrameworkError } = require("./framework-error");
@@ -43,6 +48,22 @@ class AuthHeaderError extends FrameworkError {
   }
 }
 
+/**
+ * @primitive b.authHeader.bearer
+ * @signature b.authHeader.bearer(token)
+ * @since     0.5.0
+ * @related   b.authHeader.basic, b.authHeader.fromConfig
+ *
+ * Build an `{ Authorization: "Bearer <token>" }` header object from a
+ * non-empty string token. The token is passed through verbatim — no
+ * encoding, no whitespace trimming — because RFC 6750 b64token tokens
+ * are already in the legal Authorization-value alphabet. Empty / null /
+ * non-string input throws `AuthHeaderError`.
+ *
+ * @example
+ *   var headers = b.authHeader.bearer("eyJhbGciOiJIUzI1NiJ9.payload.sig");
+ *   // → { Authorization: "Bearer eyJhbGciOiJIUzI1NiJ9.payload.sig" }
+ */
 function bearer(token) {
   if (typeof token !== "string" || token.length === 0) {
     throw new AuthHeaderError("bearer: token must be a non-empty string");
@@ -50,6 +71,23 @@ function bearer(token) {
   return { Authorization: "Bearer " + token };
 }
 
+/**
+ * @primitive b.authHeader.basic
+ * @signature b.authHeader.basic(username, password)
+ * @since     0.5.0
+ * @related   b.authHeader.bearer, b.authHeader.fromConfig
+ *
+ * Build an `{ Authorization: "Basic <base64(user:pass)>" }` header per
+ * RFC 7617. Empty username + empty password is accepted (some legacy
+ * endpoints want literal `Basic <b64('::')>`), but `null` / `undefined`
+ * username throws `AuthHeaderError` to refuse the silent-bug shape
+ * `Basic <b64('undefined:...')>`. `password === null` is normalized to
+ * an empty string.
+ *
+ * @example
+ *   var headers = b.authHeader.basic("svc-account", "s3cr3t");
+ *   // → { Authorization: "Basic c3ZjLWFjY291bnQ6czNjcjN0" }
+ */
 function basic(username, password) {
   // Accepting empty username + empty password reflects RFC 7617's
   // tolerance — some legacy endpoints want literally "Basic <b64('::')>".
@@ -63,6 +101,35 @@ function basic(username, password) {
   return { Authorization: "Basic " + b64 };
 }
 
+/**
+ * @primitive b.authHeader.fromConfig
+ * @signature b.authHeader.fromConfig(config)
+ * @since     0.5.0
+ * @related   b.authHeader.bearer, b.authHeader.basic
+ *
+ * Dispatch by the `auth` field on a consumer config object — the
+ * shared shape every framework outbound consumer accepts. Returns an
+ * empty object for `auth: "none"` (or a missing config), routes to
+ * `bearer(token)` for `auth: "bearer"`, and to `basic(username,
+ * password)` for `auth: "basic"`. Any other `auth` value throws
+ * `AuthHeaderError` with the `auth-header/unknown-method` code so a
+ * typo doesn't silently produce an unauthenticated request.
+ *
+ * @opts
+ *   {
+ *     auth?:     "none" | "bearer" | "basic",  // default: "none"
+ *     token?:    string,                       // required when auth === "bearer"
+ *     username?: string,                       // required when auth === "basic"
+ *     password?: string,                       // optional when auth === "basic"
+ *   }
+ *
+ * @example
+ *   var headers = b.authHeader.fromConfig({
+ *     auth:  "bearer",
+ *     token: "eyJhbGciOiJIUzI1NiJ9.payload.sig",
+ *   });
+ *   // → { Authorization: "Bearer eyJhbGciOiJIUzI1NiJ9.payload.sig" }
+ */
 function fromConfig(config) {
   if (!config || !config.auth || config.auth === "none") return {};
   if (config.auth === "bearer") return bearer(config.token);

package/lib/backup/bundle.js

@@ -191,6 +191,32 @@ async function create(opts) {
     files:        fileEntries,
     metadata:     opts.metadata || undefined,
   });
+  // Sign the manifest with the audit-sign keypair so a tampered
+  // manifest fails verification on restore. The signer is best-
+  // effort: callers running outside an audit-sign-initialized process
+  // (CLI tooling, ad-hoc bundlers) can pass `opts.sign: false` to
+  // emit an unsigned bundle. Default ON to match the rest of the
+  // framework's signed-by-default posture.
+  var shouldSign = opts.sign !== false;
+  if (shouldSign) {
+    try { backupManifest.sign(manifest); }
+    catch (e) {
+      var msg = (e && e.message) || String(e);
+      // auditSign.init() not awaited yet — emit unsigned bundle. Callers
+      // running outside the framework's boot sequence (CLI tooling,
+      // ad-hoc bundlers, primitive smoke tests) can finish without a
+      // signed manifest; restore-side `requireSignature: true` opt
+      // refuses any unsigned manifest.
+      if (msg.indexOf("auditSign.init() must be awaited") !== -1) {
+        _emit(progress, { phase: "manifest-unsigned", reason: "audit-sign-not-initialized" });
+      } else if (opts.signOptional === true) {
+        _emit(progress, { phase: "manifest-unsigned", reason: msg });
+      } else {
+        throw new BackupBundleError("backup-bundle/sign-failed",
+          "create: manifest sign failed: " + msg);
+      }
+    }
+  }
   var manifestPath = path.join(outDir, "manifest.json");
   atomicFile.writeSync(manifestPath, backupManifest.serialize(manifest), { fileMode: 0o600 });