@atlasent/sdk 2.5.0 → 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -0
- package/dist/hono.cjs +445 -11
- package/dist/hono.cjs.map +1 -1
- package/dist/hono.d.cts +2 -2
- package/dist/hono.d.ts +2 -2
- package/dist/hono.js +445 -11
- package/dist/hono.js.map +1 -1
- package/dist/index.cjs +2185 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1699 -180
- package/dist/index.d.ts +1699 -180
- package/dist/index.js +2159 -13
- package/dist/index.js.map +1 -1
- package/dist/{protect-DiRVfVLq.d.cts → protect-C0t0fP1y.d.cts} +449 -2
- package/dist/{protect-DiRVfVLq.d.ts → protect-C0t0fP1y.d.ts} +449 -2
- package/package.json +6 -1
|
@@ -45,7 +45,7 @@ declare class StreamParseError extends Error {
|
|
|
45
45
|
constructor(rawData: string, cause?: unknown);
|
|
46
46
|
}
|
|
47
47
|
/** Discriminator for {@link AtlaSentError.code}. */
|
|
48
|
-
type AtlaSentErrorCode = "invalid_api_key" | "forbidden" | "rate_limited" | "timeout" | "network" | "bad_response" | "bad_request" | "server_error" | "feature_disabled";
|
|
48
|
+
type AtlaSentErrorCode = "invalid_api_key" | "forbidden" | "rate_limited" | "timeout" | "network" | "bad_response" | "bad_request" | "server_error" | "feature_disabled" | "claim_evidence_incomplete";
|
|
49
49
|
/** Initialization options for {@link AtlaSentError}. */
|
|
50
50
|
interface AtlaSentErrorInit {
|
|
51
51
|
status?: number;
|
|
@@ -686,6 +686,40 @@ interface DeployGateResponse {
|
|
|
686
686
|
/** Best-effort audit/evidence metadata available to the SDK. */
|
|
687
687
|
evidence: DeployGateEvidence;
|
|
688
688
|
}
|
|
689
|
+
/**
|
|
690
|
+
* Frozen BVS snapshot wire shape (BI4).
|
|
691
|
+
* Carried in {@link EvaluateRequest}.context.bvsSnapshot when
|
|
692
|
+
* the `behavior_conditioning` flag is enabled for the tenant.
|
|
693
|
+
* Produced by behavior-insights GET /api/patterns/snapshot/:userId
|
|
694
|
+
* and attached via `@atlasent/behavior` attachToEvaluate().
|
|
695
|
+
*/
|
|
696
|
+
interface BvsSnapshot {
|
|
697
|
+
user_id: string;
|
|
698
|
+
/** Factor model output — keyed by BVS factor slug, value is score 0-1. */
|
|
699
|
+
factors: Record<string, number>;
|
|
700
|
+
/** Aggregate confidence score (0-1). Decays on a 60-day half-life. */
|
|
701
|
+
confidence: number;
|
|
702
|
+
/** True when the aggregate is fresh-and-thin (too few events to trust). */
|
|
703
|
+
confidence_low: boolean;
|
|
704
|
+
/** ISO-8601 timestamp of the compute run that produced this snapshot. */
|
|
705
|
+
computed_at: string;
|
|
706
|
+
}
|
|
707
|
+
/**
|
|
708
|
+
* Consent-class projection (BI5) — the privacy-safe aggregate shape that
|
|
709
|
+
* third-party apps (LedgersMe, hiCoach, echobloom) receive when reading a
|
|
710
|
+
* user's behavioral summary. Counts and timestamps only; no raw free-text.
|
|
711
|
+
* Produced by behavior-insights `/api/patterns/summary/:userId` and fetched
|
|
712
|
+
* via `@atlasent/behavior` getStateSummary(). The SDK enforces
|
|
713
|
+
* {@link https://github.com/AtlaSent-Systems-Inc/atlasent-sdk | assertNoRawText}
|
|
714
|
+
* client-side before returning this shape to callers.
|
|
715
|
+
*/
|
|
716
|
+
interface ConsentClassProjection {
|
|
717
|
+
user_id: string;
|
|
718
|
+
window_start: string;
|
|
719
|
+
window_end: string;
|
|
720
|
+
event_count: number;
|
|
721
|
+
category_counts: Partial<Record<string, number>>;
|
|
722
|
+
}
|
|
689
723
|
/** Input to {@link AtlaSentClient.evaluate}. */
|
|
690
724
|
interface EvaluateRequest {
|
|
691
725
|
/** Identifier of the calling agent (e.g. "clinical-data-agent"). */
|
|
@@ -694,6 +728,12 @@ interface EvaluateRequest {
|
|
|
694
728
|
action: string;
|
|
695
729
|
/** Arbitrary policy context (user, environment, resource IDs). */
|
|
696
730
|
context?: Record<string, unknown>;
|
|
731
|
+
/**
|
|
732
|
+
* When `true`, the server populates `riskEnvelope.factors` with a
|
|
733
|
+
* per-factor breakdown of the weighted risk score. Omit (or `false`)
|
|
734
|
+
* to keep response payloads small.
|
|
735
|
+
*/
|
|
736
|
+
explain?: boolean;
|
|
697
737
|
}
|
|
698
738
|
/**
|
|
699
739
|
* Slim permit object embedded in {@link EvaluateResponse} when the decision
|
|
@@ -793,6 +833,43 @@ interface EvaluateResponse {
|
|
|
793
833
|
* `X-RateLimit-*` headers. `null` when the server didn't emit them.
|
|
794
834
|
*/
|
|
795
835
|
rateLimit: RateLimitState | null;
|
|
836
|
+
/**
|
|
837
|
+
* Risk envelope summary from the policy engine. Present on all responses
|
|
838
|
+
* from engine version wire-v1@1.0.0+. Provides the weighted risk score,
|
|
839
|
+
* the pre/post-promotion decisions, and (when evaluate was called with
|
|
840
|
+
* `explain: true`) a per-factor breakdown.
|
|
841
|
+
*
|
|
842
|
+
* The envelope can only raise severity — it structurally cannot soften
|
|
843
|
+
* a deny to allow. When `promoted` is true the live `decision` was
|
|
844
|
+
* upgraded from `engineDecision` to `envelopeDecision`.
|
|
845
|
+
*/
|
|
846
|
+
riskEnvelope?: EvaluateRiskEnvelope;
|
|
847
|
+
}
|
|
848
|
+
/** Per-factor contribution in a {@link EvaluateRiskEnvelope}. */
|
|
849
|
+
interface EvaluateRiskEnvelopeFactor {
|
|
850
|
+
/** Factor identifier, e.g. `"ACTION_SENSITIVITY"`. */
|
|
851
|
+
factor: string;
|
|
852
|
+
/** Factor score in [0, 1]. Higher = more risk. */
|
|
853
|
+
value: number;
|
|
854
|
+
/** Configured weight for this factor. */
|
|
855
|
+
weight: number;
|
|
856
|
+
/** Human-readable explanation for the score. */
|
|
857
|
+
reason: string;
|
|
858
|
+
}
|
|
859
|
+
/** Risk envelope summary returned in a top-level {@link EvaluateResponse}. */
|
|
860
|
+
interface EvaluateRiskEnvelope {
|
|
861
|
+
/** Weighted risk score in [0, 1]. Score ≥ 0.70 triggers a hold. */
|
|
862
|
+
weightedScore: number;
|
|
863
|
+
/** Policy engine decision before envelope promotion. */
|
|
864
|
+
engineDecision: Decision;
|
|
865
|
+
/** Decision resolved by the risk envelope. */
|
|
866
|
+
envelopeDecision: Decision;
|
|
867
|
+
/** `true` when the envelope raised the decision's severity (most-restrictive-wins). */
|
|
868
|
+
promoted: boolean;
|
|
869
|
+
/** Deny codes that unconditionally block regardless of score. */
|
|
870
|
+
hardBlocks: string[];
|
|
871
|
+
/** Per-factor breakdown. Present only when `explain: true` was passed. */
|
|
872
|
+
factors?: EvaluateRiskEnvelopeFactor[];
|
|
796
873
|
}
|
|
797
874
|
/** Input to {@link AtlaSentClient.verifyPermit}. */
|
|
798
875
|
interface VerifyPermitRequest {
|
|
@@ -838,6 +915,11 @@ interface VerifyPermitResponse {
|
|
|
838
915
|
permitHash: string;
|
|
839
916
|
/** ISO 8601 timestamp of the verification. */
|
|
840
917
|
timestamp: string;
|
|
918
|
+
/**
|
|
919
|
+
* ISO-8601 expiration timestamp of the permit. `null` on pre-rollout
|
|
920
|
+
* server versions that do not yet surface this field.
|
|
921
|
+
*/
|
|
922
|
+
expiresAt: string | null;
|
|
841
923
|
/**
|
|
842
924
|
* Per-key rate-limit state for this request's response, parsed from
|
|
843
925
|
* `X-RateLimit-*` headers. `null` when the server didn't emit them.
|
|
@@ -1265,6 +1347,307 @@ interface StreamProgressEvent {
|
|
|
1265
1347
|
}
|
|
1266
1348
|
/** Union of all events yielded by {@link AtlaSentClient.protectStream}. */
|
|
1267
1349
|
type StreamEvent = StreamDecisionEvent | StreamProgressEvent;
|
|
1350
|
+
/**
|
|
1351
|
+
* A single item in a {@link AtlaSentClient.evaluateBatch} call.
|
|
1352
|
+
* Same shape as {@link EvaluateRequest}.
|
|
1353
|
+
*/
|
|
1354
|
+
interface BatchEvalItem {
|
|
1355
|
+
/** Identifier of the calling agent. */
|
|
1356
|
+
agent: string;
|
|
1357
|
+
/** The action being authorized. */
|
|
1358
|
+
action: string;
|
|
1359
|
+
/** Arbitrary policy context. */
|
|
1360
|
+
context?: Record<string, unknown>;
|
|
1361
|
+
}
|
|
1362
|
+
/**
|
|
1363
|
+
* Per-item result in an {@link EvaluateBatchResponse}.
|
|
1364
|
+
*
|
|
1365
|
+
* Success items carry `decision`, `decisionId`, `permitToken`, `auditHash`,
|
|
1366
|
+
* and `timestamp`. Error items (when the per-item RPC layer failed) carry
|
|
1367
|
+
* only `index`, `error`, and optionally `message`.
|
|
1368
|
+
*/
|
|
1369
|
+
interface EvaluateBatchResultItem {
|
|
1370
|
+
/** 0-based position matching the input order. */
|
|
1371
|
+
index: number;
|
|
1372
|
+
/**
|
|
1373
|
+
* Policy decision for this item. Present on success items.
|
|
1374
|
+
* `"allow"`, `"deny"`, `"hold"`, or `"escalate"`.
|
|
1375
|
+
*/
|
|
1376
|
+
decision?: DecisionCanonical;
|
|
1377
|
+
/** Server-assigned permit / decision identifier. */
|
|
1378
|
+
decisionId?: string;
|
|
1379
|
+
/** Opaque permit token (allow decisions only). Pass to verifyPermit(). */
|
|
1380
|
+
permitToken?: string | null;
|
|
1381
|
+
/** Machine-readable denial / hold reason. */
|
|
1382
|
+
reason?: string;
|
|
1383
|
+
/** Hash-chained audit-trail entry. */
|
|
1384
|
+
auditHash?: string;
|
|
1385
|
+
/** ISO-8601 decision timestamp. */
|
|
1386
|
+
timestamp?: string;
|
|
1387
|
+
/** Error code when the item itself failed at the RPC layer. */
|
|
1388
|
+
error?: string;
|
|
1389
|
+
/** Human-readable detail when `error` is set. */
|
|
1390
|
+
message?: string;
|
|
1391
|
+
}
|
|
1392
|
+
/**
|
|
1393
|
+
* Response from {@link AtlaSentClient.evaluateBatch}.
|
|
1394
|
+
*
|
|
1395
|
+
* - `items` is in the same order as the input `requests` array.
|
|
1396
|
+
* - `partial: true` means at least one item errored at the RPC layer
|
|
1397
|
+
* (not a policy deny — those are surfaced via `decision: "deny"` on
|
|
1398
|
+
* the item). Check `item.error` on items without a `decision`.
|
|
1399
|
+
* - `replayed: true` means the response was served from the idempotency
|
|
1400
|
+
* cache (a prior call with the same `batchId` completed within 24 h).
|
|
1401
|
+
*/
|
|
1402
|
+
interface BatchEvalResponse {
|
|
1403
|
+
/** Server-assigned (or caller-supplied) batch identifier. */
|
|
1404
|
+
batchId: string;
|
|
1405
|
+
/** Per-item results, in input order. */
|
|
1406
|
+
items: EvaluateBatchResultItem[];
|
|
1407
|
+
/** `true` when at least one item failed at the RPC layer. */
|
|
1408
|
+
partial: boolean;
|
|
1409
|
+
/** `true` when served from the idempotency cache. */
|
|
1410
|
+
replayed?: boolean;
|
|
1411
|
+
/** Rate-limit state from the batch response headers. */
|
|
1412
|
+
rateLimit: RateLimitState | null;
|
|
1413
|
+
}
|
|
1414
|
+
/**
|
|
1415
|
+
* Options for {@link AtlaSentClient.subscribeDecisions}.
|
|
1416
|
+
*/
|
|
1417
|
+
interface SubscribeDecisionsOptions {
|
|
1418
|
+
/**
|
|
1419
|
+
* Filter to specific event types (e.g. `["evaluate.allow", "evaluate.deny"]`).
|
|
1420
|
+
* Omit to receive all types.
|
|
1421
|
+
*/
|
|
1422
|
+
types?: string[];
|
|
1423
|
+
/** Filter to a specific actor ID. */
|
|
1424
|
+
actorId?: string;
|
|
1425
|
+
/**
|
|
1426
|
+
* Resume from a prior event. Pass the `id` of the last received event.
|
|
1427
|
+
* The server replays everything after that sequence position, then
|
|
1428
|
+
* transitions to live polling.
|
|
1429
|
+
*/
|
|
1430
|
+
lastEventId?: string;
|
|
1431
|
+
/**
|
|
1432
|
+
* Maximum session duration in seconds. The server emits `session_end`
|
|
1433
|
+
* and closes after this window; the caller should reconnect with the
|
|
1434
|
+
* last received `lastEventId`. Defaults to 1800 (30 min), max 3600 (1 h).
|
|
1435
|
+
*/
|
|
1436
|
+
maxSeconds?: number;
|
|
1437
|
+
/** Abort signal to cancel the stream. */
|
|
1438
|
+
signal?: AbortSignal;
|
|
1439
|
+
}
|
|
1440
|
+
/**
|
|
1441
|
+
* A single event from {@link AtlaSentClient.subscribeDecisions}.
|
|
1442
|
+
*
|
|
1443
|
+
* The `type` field maps to the audit-event type emitted by the server
|
|
1444
|
+
* (e.g. `"evaluate.allow"`, `"evaluate.deny"`, `"permit.verified"`).
|
|
1445
|
+
* `"heartbeat"` is a synthetic type emitted by the SDK — not a server
|
|
1446
|
+
* event — indicating the server sent a keepalive ping.
|
|
1447
|
+
* `"session_end"` signals the server-side max-seconds limit was reached;
|
|
1448
|
+
* reconnect with `lastEventId` to continue.
|
|
1449
|
+
*/
|
|
1450
|
+
interface DecisionStreamEvent {
|
|
1451
|
+
/** Stable server-assigned ID. Pass as `lastEventId` to resume. */
|
|
1452
|
+
id?: string;
|
|
1453
|
+
/**
|
|
1454
|
+
* Audit-event type, e.g. `"evaluate.allow"`, `"evaluate.deny"`,
|
|
1455
|
+
* `"evaluate.hold"`, `"permit.verified"`, `"permit.revoked"`,
|
|
1456
|
+
* `"heartbeat"`, `"session_end"`.
|
|
1457
|
+
*/
|
|
1458
|
+
type: string;
|
|
1459
|
+
decision?: DecisionCanonical;
|
|
1460
|
+
actorId?: string;
|
|
1461
|
+
resourceType?: string;
|
|
1462
|
+
resourceId?: string;
|
|
1463
|
+
payload?: Record<string, unknown>;
|
|
1464
|
+
hash?: string;
|
|
1465
|
+
previousHash?: string;
|
|
1466
|
+
occurredAt?: string;
|
|
1467
|
+
}
|
|
1468
|
+
|
|
1469
|
+
/**
|
|
1470
|
+
* Evidence Engine — per-decision proof artifacts, "why" traces, and
|
|
1471
|
+
* compliance-ready bundles.
|
|
1472
|
+
*
|
|
1473
|
+
* Turn every AtlaSent decision into tamper-evident proof that buyers
|
|
1474
|
+
* can hand to auditors, compliance teams, and regulators.
|
|
1475
|
+
*
|
|
1476
|
+
* Primary entry points:
|
|
1477
|
+
*
|
|
1478
|
+
* 1. `buildWhyTrace(decision, reasons, constraintTrace)` — converts
|
|
1479
|
+
* the ConstraintTrace from `?include=constraint_trace` into a
|
|
1480
|
+
* structured human/machine-readable "why allowed / why denied" trace.
|
|
1481
|
+
*
|
|
1482
|
+
* 2. `buildDecisionReceiptPayload(args)` — assembles the canonical
|
|
1483
|
+
* signable payload for a per-decision receipt.
|
|
1484
|
+
*
|
|
1485
|
+
* 3. `signDecisionReceiptHmac(payload, secret)` — HMAC-SHA256 sign.
|
|
1486
|
+
*
|
|
1487
|
+
* 4. `verifyDecisionReceiptHmac(receipt, secret)` — offline verify.
|
|
1488
|
+
*
|
|
1489
|
+
* 5. `computeBundleHash(bundle)` — SHA-256 of an ActionEvidenceBundle.
|
|
1490
|
+
*
|
|
1491
|
+
* 6. `soc2ControlCoverageForDecision(opts)` — map a decision to SOC 2
|
|
1492
|
+
* control coverage.
|
|
1493
|
+
*
|
|
1494
|
+
* The {@link DecisionReceipt} is the category-defining artifact: a
|
|
1495
|
+
* self-contained, signed, human-readable proof that a specific action
|
|
1496
|
+
* was (or was not) authorized at a specific moment. Every enforcement
|
|
1497
|
+
* adapter produces one; every compliance bundle includes one.
|
|
1498
|
+
*/
|
|
1499
|
+
|
|
1500
|
+
/**
|
|
1501
|
+
* One evaluated stage within a policy, in the order the engine ran it.
|
|
1502
|
+
*/
|
|
1503
|
+
interface WhyStage {
|
|
1504
|
+
/** Engine stage name (e.g. `"role_check"`, `"context"`). */
|
|
1505
|
+
stage: string;
|
|
1506
|
+
/** Rule identifier, if the stage is rule-bound. */
|
|
1507
|
+
rule?: string;
|
|
1508
|
+
/** Whether this stage's predicate fired / matched. */
|
|
1509
|
+
matched: boolean;
|
|
1510
|
+
/** Non-obvious detail from the engine. */
|
|
1511
|
+
detail?: string;
|
|
1512
|
+
/**
|
|
1513
|
+
* Impact classification:
|
|
1514
|
+
* - `"terminal"` — this stage caused the outer decision.
|
|
1515
|
+
* - `"contributing"` — matched but was not the decisive stage.
|
|
1516
|
+
* - `"passing"` — did not match; execution continued.
|
|
1517
|
+
*/
|
|
1518
|
+
impact: "terminal" | "contributing" | "passing";
|
|
1519
|
+
}
|
|
1520
|
+
/** Per-policy evaluation block within a WhyTrace. */
|
|
1521
|
+
interface WhyPolicyEvaluation {
|
|
1522
|
+
policy_id: string;
|
|
1523
|
+
/** Policy-level decision. */
|
|
1524
|
+
decision: string;
|
|
1525
|
+
/** Engine-side fingerprint of the policy bundle row. */
|
|
1526
|
+
fingerprint: string;
|
|
1527
|
+
/** Optional risk score from a `risk` rule clause. */
|
|
1528
|
+
risk_score?: number;
|
|
1529
|
+
/** Stages evaluated for this policy, in order. */
|
|
1530
|
+
stages: WhyStage[];
|
|
1531
|
+
/** `true` iff this policy's decision drove the outer envelope decision. */
|
|
1532
|
+
was_decisive: boolean;
|
|
1533
|
+
}
|
|
1534
|
+
/**
|
|
1535
|
+
* Structured "why allowed / why denied" trace.
|
|
1536
|
+
*
|
|
1537
|
+
* Produced by `buildWhyTrace()` from the `ConstraintTrace` returned
|
|
1538
|
+
* by `/v1-evaluate?include=constraint_trace`. Suitable for:
|
|
1539
|
+
*
|
|
1540
|
+
* - UI display ("Why was this denied?")
|
|
1541
|
+
* - Email / Slack notifications
|
|
1542
|
+
* - Compliance-bundle human-readable section
|
|
1543
|
+
* - Machine-readable policy audit by external verifiers
|
|
1544
|
+
*
|
|
1545
|
+
* `summary` is a one-sentence plain-English explanation.
|
|
1546
|
+
*/
|
|
1547
|
+
interface WhyTrace {
|
|
1548
|
+
decision: DecisionCanonical;
|
|
1549
|
+
/** One-sentence human-readable explanation. */
|
|
1550
|
+
summary: string;
|
|
1551
|
+
/** Policy whose decision drove the outer result. Absent on clean allow. */
|
|
1552
|
+
matched_policy_id?: string;
|
|
1553
|
+
/** Per-policy evaluation blocks in evaluation order. */
|
|
1554
|
+
policy_evaluations: WhyPolicyEvaluation[];
|
|
1555
|
+
/**
|
|
1556
|
+
* The single stage that caused the terminal outcome, extracted for
|
|
1557
|
+
* quick access. `undefined` on a clean allow (no blocking stage).
|
|
1558
|
+
*/
|
|
1559
|
+
terminal_stage?: WhyStage;
|
|
1560
|
+
/** Total stages evaluated across all policies. */
|
|
1561
|
+
total_stages_evaluated: number;
|
|
1562
|
+
}
|
|
1563
|
+
/** Signing algorithm tag on a {@link DecisionReceipt}. */
|
|
1564
|
+
type DecisionReceiptAlgorithm = "hmac-sha256" | "ed25519" | "none";
|
|
1565
|
+
/**
|
|
1566
|
+
* The canonical signed payload of a {@link DecisionReceipt}.
|
|
1567
|
+
*
|
|
1568
|
+
* Field order is load-bearing: HMAC and chain verifiers stringify
|
|
1569
|
+
* this object and must reproduce byte-identical output. Never reorder
|
|
1570
|
+
* the fields; add new optional fields at the end only.
|
|
1571
|
+
*/
|
|
1572
|
+
interface DecisionReceiptPayload {
|
|
1573
|
+
receipt_id: string;
|
|
1574
|
+
evaluation_id: string;
|
|
1575
|
+
org_id: string;
|
|
1576
|
+
decision: DecisionCanonical;
|
|
1577
|
+
action: string;
|
|
1578
|
+
actor: string;
|
|
1579
|
+
resource_type: string | null;
|
|
1580
|
+
resource_id: string | null;
|
|
1581
|
+
reasons: string[];
|
|
1582
|
+
/** One-sentence human-readable summary from the WhyTrace. */
|
|
1583
|
+
why_summary: string;
|
|
1584
|
+
/** Permit ID when the decision was `"allow"`. */
|
|
1585
|
+
permit_id: string | null;
|
|
1586
|
+
/** Permit verification hash when the decision was `"allow"`. */
|
|
1587
|
+
permit_hash: string | null;
|
|
1588
|
+
/** Hash-chained audit-trail entry from the evaluate response. */
|
|
1589
|
+
audit_hash: string;
|
|
1590
|
+
/** SHA-256 hex of canonical JSON of the evaluate context. */
|
|
1591
|
+
context_hash: string;
|
|
1592
|
+
/** ISO-8601 when this receipt was issued. */
|
|
1593
|
+
issued_at: string;
|
|
1594
|
+
/** ISO-8601 TTL, or `null` for non-expiring receipts. */
|
|
1595
|
+
expires_at: string | null;
|
|
1596
|
+
}
|
|
1597
|
+
/**
|
|
1598
|
+
* A signed, tamper-evident record of a single AtlaSent authorization
|
|
1599
|
+
* decision. Self-contained: contains everything an auditor needs to
|
|
1600
|
+
* verify the decision without querying the API.
|
|
1601
|
+
*
|
|
1602
|
+
* **Signature semantics (HMAC-SHA256):**
|
|
1603
|
+
*
|
|
1604
|
+
* `HMAC-SHA256(secret,
|
|
1605
|
+
* receipt_id + "\\n" + issued_at + "\\n" + JSON.stringify(payload))`
|
|
1606
|
+
*
|
|
1607
|
+
* When `algorithm === "ed25519"`, `signature` is hex-encoded Ed25519
|
|
1608
|
+
* over the same input string encoded as UTF-8.
|
|
1609
|
+
*
|
|
1610
|
+
* Offline verification: `verifyDecisionReceiptHmac(receipt, secret)`.
|
|
1611
|
+
*
|
|
1612
|
+
* Callers MUST reject receipts where `algorithm === "none"` in any
|
|
1613
|
+
* context requiring tamper-evidence.
|
|
1614
|
+
*/
|
|
1615
|
+
interface DecisionReceipt {
|
|
1616
|
+
receipt_id: string;
|
|
1617
|
+
evaluation_id: string;
|
|
1618
|
+
org_id: string;
|
|
1619
|
+
decision: DecisionCanonical;
|
|
1620
|
+
action: string;
|
|
1621
|
+
actor: string;
|
|
1622
|
+
resource_type: string | null;
|
|
1623
|
+
resource_id: string | null;
|
|
1624
|
+
reasons: string[];
|
|
1625
|
+
/**
|
|
1626
|
+
* Full structured "why" trace. `null` when the evaluation was
|
|
1627
|
+
* performed without `?include=constraint_trace`.
|
|
1628
|
+
*/
|
|
1629
|
+
why_trace: WhyTrace | null;
|
|
1630
|
+
permit_id: string | null;
|
|
1631
|
+
permit_hash: string | null;
|
|
1632
|
+
audit_hash: string;
|
|
1633
|
+
/** SHA-256 hex of canonical JSON of the evaluate context. */
|
|
1634
|
+
context_hash: string;
|
|
1635
|
+
issued_at: string;
|
|
1636
|
+
expires_at: string | null;
|
|
1637
|
+
algorithm: DecisionReceiptAlgorithm;
|
|
1638
|
+
/**
|
|
1639
|
+
* Hex (HMAC-SHA256 or Ed25519) signature, or `null` when
|
|
1640
|
+
* `algorithm === "none"`.
|
|
1641
|
+
*/
|
|
1642
|
+
signature: string | null;
|
|
1643
|
+
/** Registry key ID that signed, when `algorithm !== "none"`. */
|
|
1644
|
+
signing_key_id: string | null;
|
|
1645
|
+
/**
|
|
1646
|
+
* Full payload that was signed. Pass to `verifyDecisionReceiptHmac`
|
|
1647
|
+
* or reconstruct independently for external verification.
|
|
1648
|
+
*/
|
|
1649
|
+
payload: DecisionReceiptPayload;
|
|
1650
|
+
}
|
|
1268
1651
|
|
|
1269
1652
|
/** Input to {@link protect}. Same shape as `EvaluateRequest`. */
|
|
1270
1653
|
interface ProtectRequest {
|
|
@@ -1287,6 +1670,8 @@ interface Permit {
|
|
|
1287
1670
|
reason: string;
|
|
1288
1671
|
/** ISO 8601 timestamp of the verification. */
|
|
1289
1672
|
timestamp: string;
|
|
1673
|
+
/** ISO-8601 expiration timestamp of the permit. null on pre-rollout servers. */
|
|
1674
|
+
permitExpiresAt: string | null;
|
|
1290
1675
|
}
|
|
1291
1676
|
/** Configuration for the process-wide singleton used by {@link protect}. */
|
|
1292
1677
|
interface ConfigureOptions {
|
|
@@ -1325,5 +1710,67 @@ declare function deployGate(request?: DeployGateRequest): Promise<DeployGateResp
|
|
|
1325
1710
|
* or server error. Same fail-closed contract: do not proceed.
|
|
1326
1711
|
*/
|
|
1327
1712
|
declare function protect(request: ProtectRequest): Promise<Permit>;
|
|
1713
|
+
/**
|
|
1714
|
+
* A verified {@link Permit} with an embedded signed {@link DecisionReceipt}.
|
|
1715
|
+
*
|
|
1716
|
+
* Returned by {@link protectWithEvidence}. Store `receipt` alongside
|
|
1717
|
+
* your action record (deploy logs, payment records, close workflows)
|
|
1718
|
+
* to give auditors a self-contained proof of authorization.
|
|
1719
|
+
*/
|
|
1720
|
+
interface PermitWithEvidence extends Permit {
|
|
1721
|
+
/** Signed per-decision receipt. `algorithm: "none"` when no signing secret was supplied. */
|
|
1722
|
+
receipt: DecisionReceipt;
|
|
1723
|
+
}
|
|
1724
|
+
/** Options for {@link protectWithEvidence}. */
|
|
1725
|
+
interface ProtectWithEvidenceOptions {
|
|
1726
|
+
/**
|
|
1727
|
+
* HMAC-SHA256 signing secret. When provided, the receipt is signed
|
|
1728
|
+
* and can be verified offline with `verifyDecisionReceiptHmac`.
|
|
1729
|
+
* Recommend `process.env.ATLASENT_RECEIPT_SIGNING_SECRET`.
|
|
1730
|
+
*/
|
|
1731
|
+
signingSecret?: string;
|
|
1732
|
+
/**
|
|
1733
|
+
* Registry key ID recorded on the receipt, paired with `signingSecret`.
|
|
1734
|
+
* Used for key rotation: store the ID alongside the receipt so
|
|
1735
|
+
* verifiers know which key to use.
|
|
1736
|
+
*/
|
|
1737
|
+
signingKeyId?: string;
|
|
1738
|
+
/**
|
|
1739
|
+
* If you have already called `client.evaluatePreflight()` for this
|
|
1740
|
+
* request, pass `constraintTrace` here to populate
|
|
1741
|
+
* `receipt.why_trace` with the full stage-by-stage "why" trace.
|
|
1742
|
+
* When omitted, `why_trace` is `null` on the receipt.
|
|
1743
|
+
*/
|
|
1744
|
+
constraintTrace?: ConstraintTrace | null;
|
|
1745
|
+
}
|
|
1746
|
+
/**
|
|
1747
|
+
* Authorize an action end-to-end and mint a signed {@link DecisionReceipt}.
|
|
1748
|
+
*
|
|
1749
|
+
* Same fail-closed contract as {@link protect} — throws
|
|
1750
|
+
* {@link AtlaSentDeniedError} on deny, {@link AtlaSentError} on
|
|
1751
|
+
* transport failure. The action MUST NOT proceed if this throws.
|
|
1752
|
+
*
|
|
1753
|
+
* On allow, returns the verified `Permit` plus a signed `DecisionReceipt`
|
|
1754
|
+
* that captures:
|
|
1755
|
+
* - The evaluation ID and decision
|
|
1756
|
+
* - Human-readable reasons
|
|
1757
|
+
* - Permit ID and hash
|
|
1758
|
+
* - Audit-trail hash (hash-chain link)
|
|
1759
|
+
* - SHA-256 of the evaluate context (tamper-evidence for the inputs)
|
|
1760
|
+
* - Optional "why" trace (pass `constraintTrace` from `evaluatePreflight`)
|
|
1761
|
+
*
|
|
1762
|
+
* ```ts
|
|
1763
|
+
* const { permit, receipt } = await protectWithEvidence(
|
|
1764
|
+
* { agent: "deploy-bot", action: "production.deploy", context },
|
|
1765
|
+
* {
|
|
1766
|
+
* signingSecret: process.env.ATLASENT_RECEIPT_SIGNING_SECRET,
|
|
1767
|
+
* signingKeyId: "key-v1",
|
|
1768
|
+
* },
|
|
1769
|
+
* );
|
|
1770
|
+
* // Store alongside the deployment record.
|
|
1771
|
+
* await db.deployments.create({ commitSha, permit, receipt });
|
|
1772
|
+
* ```
|
|
1773
|
+
*/
|
|
1774
|
+
declare function protectWithEvidence(request: ProtectRequest, opts?: ProtectWithEvidenceOptions): Promise<PermitWithEvidence>;
|
|
1328
1775
|
|
|
1329
|
-
export { type
|
|
1776
|
+
export { type ConstraintTrace as $, AtlaSentDeniedError as A, type BatchEvalItem as B, protect as C, type DecisionCanonical as D, type EvaluateRequest as E, deployGate as F, type GetPermitResponse as G, configure as H, type AtlaSentDecision as I, type AtlaSentDeniedErrorInit as J, type AtlaSentErrorCode as K, type ListPermitsRequest as L, type AtlaSentErrorInit as M, AtlaSentEscalateError as N, type AtlaSentEscalateErrorInit as O, type Permit as P, type AuditDecision as Q, type RateLimitState as R, type SubscribeDecisionsOptions as S, type AuditEvent as T, type AuditEventsPage as U, type VerifyPermitRequest as V, type AuditExport as W, type AuditExportSignatureStatus as X, type BvsSnapshot as Y, type ConfigureOptions as Z, type ConsentClassProjection as _, AtlaSentError as a, type ConstraintTracePolicy as a0, type ConstraintTraceStage as a1, DEFAULT_RETRY_POLICY as a2, DEPLOYMENT_PRODUCTION_ACTION as a3, DEPLOY_GATE_CODES as a4, type Decision as a5, type DeployGateContext as a6, type DeployGateDenyCode as a7, type DeployGateEvidence as a8, type DeployOverrideClaim as a9, type DeployPermitClaim as aa, type EvaluateBatchResultItem as ab, type EvaluateResponsePermit as ac, type EvaluateRiskEnvelope as ad, type EvaluateRiskEnvelopeFactor as ae, PRODUCTION_DEPLOY_ACTION as af, type PermitOutcome as ag, type PermitRecord as ah, PermitRevoked as ai, type PermitStatus as aj, type PermitWithEvidence as ak, type ProtectWithEvidenceOptions as al, type RetryPolicy as am, type StreamDecisionEvent as an, StreamParseError as ao, type StreamProgressEvent as ap, StreamTimeoutError as aq, computeBackoffMs as ar, hasAttemptsLeft as as, isRetryable as at, mergePolicy as au, normalizePermitOutcome as av, protectWithEvidence as aw, type ProtectRequest as b, type AtlaSentClientOptions as c, type EvaluateResponse as d, type BatchEvalResponse as e, type DecisionStreamEvent as f, type EvaluatePreflightResponse as g, type VerifyPermitResponse as h, type DeployGateRequest as i, type DeployGateResponse as j, type RevokePermitRequest as k, type RevokePermitResponse as l, type RevokePermitByIdInput as m, type RevokePermitByIdResponse as n, type VerifyPermitByIdResponse as o, type PermitValidResponse as p, type ListPermitsResponse as q, type ApiKeySelfResponse as r, type AuditEventsQuery as s, type AuditEventsResult as t, type AuditExportRequest as u, type AuditExportResult as v, type StreamOptions as w, type StreamEvent as x, type DecisionReceipt as y, type DecisionReceiptAlgorithm as z };
|