@bivelio/savings-layer 0.4.20 → 0.4.21

package/dist/index.d.ts

@@ -205,7 +205,7 @@ declare function precioDeLista(model: string): CostModel | undefined;
  * on the customer's machine. `test/version-declarada.test.ts` ties this
  * constant to package.json so the two can never drift.
  */
-declare const BV_SALA_VERSION = "0.4.20";
+declare const BV_SALA_VERSION = "0.4.21";
 
 /**
  * Environment-agnostic UUID generation.
@@ -990,6 +990,15 @@ interface LicenseGate {
      * que tener una rama por defecto de todas formas.
      */
     status?(): string;
+    /**
+     * Why the key does not open, when it does not; `undefined` when it does. It
+     * only refines the MESSAGE, never the verdict: an `"invalid"` whose reason is
+     * `"malformed"` (not even the shape of a token: the `bvk_` pasted where the
+     * license goes) gets different advice from an `"invalid"` that has the shape
+     * but no valid signature. Optional because a gate is implemented by the
+     * caller; without it, the generic message for that status.
+     */
+    reason?(): string | undefined;
 }
 interface TraceEvent {
     stage: string;
@@ -2575,8 +2584,14 @@ declare class LicenseError extends Error {
  *
  * El comportamiento no cambia —sigue siendo fail-closed, `granted()` no lo
  * concede— pero ahora el mensaje puede decir la verdad.
+ *
+ * `none` means "there is no key": what is left after `normalizeLicenseKey` is
+ * EMPTY. It is the same value `LicenseError.status` already carries when nothing
+ * was configured, because it is the same problem with the same fix: a
+ * `licenseKey: "   "` (an empty environment variable, a blank secret file) used
+ * to tell the customer their key "does not verify" — there was no key.
  */
-type LicenseStatus = "active" | "grace" | "expired" | "invalid" | "revoked" | "stale";
+type LicenseStatus = "active" | "grace" | "expired" | "invalid" | "revoked" | "stale" | "none";
 /** Decoded license token body (mirror of `@bivelio/protocol`'s LicensePayload,
  *  declared locally so the SDK stays free of a control-plane dependency). */
 interface LicenseTokenPayload {
@@ -2621,6 +2636,48 @@ interface LicenseKeyset {
 }
 /** Narrow a verification key to a {@link LicenseKeyset} (vs a bare SPKI PEM string). */
 declare function isKeyset(k: string | LicenseKeyset): k is LicenseKeyset;
+/**
+ * Normalize a license key the way it arrives from the real world — ONCE, at the
+ * entry point, never inside the verifier.
+ *
+ * The README says `export BIVELIO_LICENSE_KEY=…` and dotenv trims, so that path
+ * never showed it. But anyone reading the key from a file (`readFileSync`), from
+ * a Docker/Kubernetes secret (mounted as a file, trailing newline included) or
+ * copying it out of an `Authorization` header handed over a CORRECT key with a
+ * `\n` after it, a space before it, quotes around it or a `Bearer ` in front —
+ * and the SDK answered "does not verify, check you pasted the WHOLE key". A
+ * wrong diagnosis on a good key is the worst possible hint: it sends the
+ * customer to look where the problem is not.
+ *
+ * Worse, it was INCONSISTENT: `tok + "\r\n"` passed and `tok + "\n"` did not,
+ * because `atob` ignores ASCII whitespace while the padding was computed from a
+ * length that included it, and two extra characters give the same remainder
+ * modulo 4 as zero. Behavior that depends on which editor saved the file is not
+ * behavior.
+ *
+ * Only OUTER wrapping is removed — whitespace, one pair of single or double
+ * quotes, a `Bearer` prefix in any capitalization — in that order, in one pass.
+ * Anything INSIDE the key is left alone: an interior space is not wrapping, it
+ * is a broken key, and {@link licenseKeyShape} reports it as `malformed`.
+ */
+declare function normalizeLicenseKey(raw: string): string;
+/**
+ * The SHAPE of an already-normalized key, so the error message can tell apart
+ * three problems that used to get the same text:
+ *
+ *   · `empty`     — there is no key (only whitespace, or nothing at all).
+ *   · `malformed` — not even the shape of a token: not three dot-separated
+ *                   base64url segments. This is where the `bvk_` service key
+ *                   pasted where the license goes lands, as does arbitrary text
+ *                   or a token with a line break in the middle.
+ *   · `token`     — has the shape; whether it verifies is up to the signature.
+ *
+ * It is the SAME shape rule {@link verifyCompactSignature} enforces, so that "has
+ * the shape" and "verification was attempted" mean the same thing.
+ */
+type LicenseKeyShape = "empty" | "malformed" | "token";
+/** Classify a normalized key. See {@link LicenseKeyShape}. */
+declare function licenseKeyShape(normalizedKey: string): LicenseKeyShape;
 /**
  * Verify the Ed25519 signature of any BV-SALA compact token
  * (`base64url(header).base64url(body).base64url(sig)`, sig over `${head}.${body}`)
@@ -2629,6 +2686,13 @@ declare function isKeyset(k: string | LicenseKeyset): k is LicenseKeyset;
  * so the browser (`@noble/curves`) and node (`node:crypto`) sides agree byte-for-byte
  * and there is no bespoke per-message verification path to keep in sync. It does NOT
  * interpret the payload or the header `typ` — callers do that.
+ *
+ * Shape is checked SEGMENT by segment, not just by counting dots. Three parts
+ * used to be enough and the rest was left to `atob`, which ignores whitespace:
+ * that is how a token with `\r\n` after it verified while the same token with
+ * `\n` did not (see {@link normalizeLicenseKey}). The shared primitive must give
+ * the same answer to the same input, always; a caller that wants to tolerate
+ * wrapping normalizes BEFORE calling.
  */
 declare function verifyCompactSignature(token: string, publicKey: string | LicenseKeyset): CompactVerification;
 /** Verify a token's signature and decode its payload. Does not check expiry. */
@@ -2656,6 +2720,9 @@ declare function deriveStatus(payload: {
  * Verify + apply the grace policy → a resolved status. Mirrors what the issuing
  * control plane resolves for the same token. Bad signature / malformed
  * → invalid; otherwise the status comes from {@link deriveStatus}.
+ *
+ * A public entry point, so it normalizes like the others (gate and refresher):
+ * the same key must resolve the same whichever way it comes in.
  */
 declare function resolveLicense(token: string, publicKey: string | LicenseKeyset, opts?: {
     nowSeconds?: number;
@@ -2732,6 +2799,15 @@ declare class RevocationSnapshot {
 interface ResolvedGate extends LicenseGate {
     isActive(): boolean;
     status(): LicenseStatus;
+    /**
+     * Why the key does not open, when it does not; `undefined` when it verified.
+     * Under `status() === "invalid"` it tells a key that does NOT EVEN HAVE THE
+     * SHAPE of a token (`"malformed"`: the `bvk_` pasted where the license goes,
+     * arbitrary text) from a well-formed one whose signature fails (the verifier's
+     * reason, e.g. `"bad signature"`). Both are `invalid` — the stable handle for
+     * branching does not change — but the advice given to the customer differs.
+     */
+    reason(): string | undefined;
     /** Unix seconds after which the online status should be re-checked (poller anchor). */
     refreshAfter?(): number | undefined;
 }
@@ -3063,6 +3139,11 @@ interface SavingsLayerConfig {
      * against the embedded public key and builds a {@link licenseGate} from it.
      * Without a valid, active license (and without {@link devUnlicensed}), the
      * pipeline refuses to run — get a key at https://savings.bivelio.com.
+     *
+     * Surrounding whitespace (the trailing newline of a file or mounted secret),
+     * wrapping quotes and a `Bearer ` prefix are stripped before verification, so
+     * a key read with `readFileSync` works as-is. Anything INSIDE the key is not
+     * touched: a key with a space in the middle is a broken key.
      */
     licenseKey?: string;
     /**
@@ -3366,4 +3447,4 @@ interface SavingsLayer {
  */
 declare function createSavingsLayer(config: Omit<SavingsLayerConfig, "tokenizer"> & Partial<Pick<SavingsLayerConfig, "tokenizer">>): SavingsLayer;
 
-export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };
+export { type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderUsage, QUALITY_STATUSES, type QualityStatus, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsReport, type SavingsRequest, type SavingsResult, type SavingsToggles, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, randomId, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sha256, shouldCompress, stableStringify, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };