@trustlayer-foundation/aria-sdk 0.0.0-stage → 1.0.1

package/API.md

@@ -0,0 +1,207 @@
+# ARIA SDK 1.0 — API contract
+
+Status: implemented, version 1.0.0: inspection, trust, credential verification,
+exact-instance status and the trust interface ARIA AP works through.
+
+This package verifies credentials and their status. Requests, admission, operations and
+receipts are **ARIA AP**, the separate package in [`../aria-ap-ts`](../aria-ap-ts/API.md),
+which builds on this one. A service that only checks credentials needs only this package.
+
+## Results, kept apart
+
+| Result | Says | Does not say |
+|---|---|---|
+| `Inspection` (`inspectCredential`) | The fields a document carries | Anything verified: `verified` is always `false` |
+| `VerifiedCredential` (`verifyCredential`) | This exact document conforms to its `spec_version`, is within its signed validity and verifies under a trusted issuer, both signature halves | Who presents it; its status |
+| `StatusEvidence` (`checkStatus`) | The status of that exact document, its source, and its times | Anything about another document of the same DID |
+| `Standing` (`standing`) | Whether that exact document stands now: valid, with fresh evidence of its status | That anyone presents it, or may do anything with it |
+| `AuthenticCredential` (`verifyAuthenticity`) | A retained document verifies under a trusted issuer as `verifyCredential` checks it, except against the current time | That it is valid now, its status, or anything a current result says |
+| `RetainedStatus` (`readRetainedStatus`) | What a retained, signed list said about that document during the list's own validity | Its status now |
+
+None of them is a decision to run anything. Who presents a credential, and what they may
+do, is ARIA AP's: its admission, not a field here, is what lets an operation run.
+
+## Results are the verifier's own: runtime provenance
+
+A result object is a deeply frozen **view**. The verifier that produced it keeps the
+authoritative snapshot in private storage keyed by that object's identity, and every
+consumer (`checkStatus`, `facts`, `standing`, and through them ARIA AP) reads the
+snapshot, never the view's fields. Therefore:
+
+- a spread copy, a copy with every own property and symbol, or a cast object is refused
+  (`AriaUsageError`), whatever it contains;
+- a view cannot be altered in place: it is frozen, times are RFC 3339 strings and the
+  holder key is its multibase string (the 32 bytes stay inside the verifier);
+- a result is accepted only by the verifier instance that produced it. A trust profile's
+  `id` (`demo`, `production`) is a label, not a trust identity: another verifier, even with
+  the same label or keys, refuses it;
+- the trusted configuration is copied and frozen when the verifier is created; later
+  changes to the caller's key bytes or arrays change nothing;
+- time-sensitive evidence is judged when it is used: `standing` judges at each call, so
+  a credential verified earlier can be expired at admission, and status evidence fresh
+  then can be stale now;
+- two installed copies of this package are two separate records: each refuses the
+  other's results, so a duplicated install fails closed, never open.
+
+Install one copy and create the verifier once per trust configuration; ARIA AP takes that
+instance (`createAp({ credentials })`) instead of creating its own.
+
+Types alone are not the boundary (a spread keeps the type); the runtime record is.
+
+## Building on this package: `facts` and `standing`
+
+ARIA AP, or any package built on this one, must reuse this verifier's work without
+trusting a result's fields: a copy, a cast or another verifier's object carries the
+same fields. Two methods are the whole interface:
+
+- **`facts(credential)`** returns what the verifier recorded for one of its own
+  `VerifiedCredential` results: binding, DID, issuer, level, scopes, `hitlRequired`,
+  delegation depth, validity, and the holder key as its 32 raw bytes. Each call returns a
+  fresh copy; changing it changes nothing the verifier holds.
+- **`standing(credential, status)`** judges, at the call and with the verifier's clock,
+  skew and maximum ages, whether that exact credential is inside its signed validity and
+  `status` is this verifier's evidence about that same result, available, fresh and
+  active. In order: `not_valid_now`; `unknown` (`other_document`, `unavailable`,
+  `stale`); `revoked`; `superseded`; `good`. Unknown is never good.
+
+Both throw `AriaUsageError` for anything this verifier did not produce. What they return
+is data and a judgment, not evidence: no entry point of this package or of ARIA AP
+accepts them in place of a result. They exist so that a package built on this one never
+reads a result's fields and never verifies a credential or its status a second time.
+
+A result is evidence only inside the process and the verifier that produced it. Data
+that crosses a process boundary is verified again where it arrives.
+
+## Trust boundary
+
+**Trusted configuration** — supplied by the adopter, never read from a message, copied
+when the verifier is created: trust profiles (issuer DID, the `verificationMethod` its
+proofs name, both public keys, highest level, the status lists it publishes, its online
+status endpoint), the fetch policy (exact allowed origins, time and size bounds, the
+fetch implementation; redirects are never followed), the clock, maximum status ages and
+clock skew. ARIA AP adds its own (receiver identity, operations, stores, approvals).
+
+**Untrusted input** — everything that arrives: credentials, status lists and online
+answers. Nothing in them selects a trust anchor or a fetch target outside the allowed
+origins.
+
+There is no global configuration and nothing embedded: a verifier trusts exactly its
+profiles. The level order is protocol, not configuration: `TRUST_LEVELS` lists the levels
+lowest first and is frozen, so no consumer can reorder the ranking this verifier and
+ARIA AP apply.
+
+## Credential verification
+
+`verifyCredential(document)` accepts an object or JSON text up to 100 KB, works on a
+private copy, and returns the first failure in this order:
+
+1. not a JSON object (`malformed`), `spec_version` other than `"1.0"` (`unsupported_version`);
+2. the AID 1.0 schema (`malformed`, with a JSON pointer);
+3. an issuer no profile names (`untrusted_issuer`);
+4. proof metadata other than the profile's — `DataIntegrityProof`,
+   `mldsa65-ed25519-2026`, `assertionMethod`, the profile's `verificationMethod`
+   (`unsupported_proof`). These values are checked, not signed: the suite signs the
+   document without its `proof`;
+5. both signature halves over the canonical document (`signature_invalid`);
+6. strict RFC 3339 validity, ordered, current within the skew (`invalid_validity`,
+   `not_yet_valid`, `expired`);
+7. the holder key: exactly 32 raw Ed25519 bytes in ARIA's own encoding, under
+   the subject's DID, and acceptable by the authority's own rule — the canonical
+   encoding of a point, not of small order, torsion free
+   (`holder_key_invalid`). The identity point and other weak keys cannot establish
+   possession, so they are refused here, not only at issuance;
+8. rules the schema cannot express: `hitlRequired` within `scope` (`semantic_invalid`);
+9. a level above the profile's maximum (`level_not_trusted`);
+10. a status list the profile does not publish (`status_list_untrusted`).
+
+The result has no issuance time: `validFrom` and `validUntil` are the signed bounds and
+`proof.created` is unsigned. `previousCredentialId` is returned as data and never fetched:
+it relates a renewal to the credential before it, and the DID does not change.
+
+## Status
+
+`checkStatus(credential, { via })` concerns the exact document:
+
+- **`status-list`** (default) fetches the list the credential names, from an allowed
+  origin, and reads it only after it verifies under the same profile: issuer, proof
+  profile, both signatures, its signed `id` equal to the list the credential names
+  (another genuine list of the same issuer is refused), the supported subject
+  (`BitstringStatusList`, purpose `revocation`, one bit per entry), and `encodedList` as
+  multibase `u` + base64url GZIP, decompressed within 2 MiB and at least 131,072 entries.
+  Its times are then judged at completion, not when the request started: a validity
+  window of at most 24 hours that holds now, and an age from its own signed `validFrom`
+  within `statusMaxAgeSeconds` (default 3600). `fetchedAt` is that completion time,
+  reported apart from the list's signed times.
+- **`online`** asks the profile's `onlineStatus` endpoint for the DID. Only a complete
+  answer counts — the DID, an exact document reference and a status; anything less is
+  `unavailable`. It has no signed time, is stamped when observed, is only as strong as
+  TLS to that configured endpoint, and `standing` treats it as fresh for
+  `onlineStatusMaxAgeSeconds` (default 60). A complete answer naming another current
+  document makes the presented one `superseded`; a revocation bit never does.
+- Anything not established is `unavailable` with a reason (`offline`, `origin_not_allowed`,
+  `fetch_failed`, `too_large`, `malformed`, `signature_invalid`, `wrong_issuer`,
+  `not_valid_now`, `stale`, `no_online_endpoint`); its standing is `unknown`, which ARIA AP's
+  admission treats as `indeterminate`.
+
+## Historical authenticity
+
+Checking a past statement (an ARIA AP receipt signed by a receiver whose credential has
+since expired) needs the document's authenticity, not its current validity. Three
+methods give that, apart from everything that judges a credential now:
+
+- **`verifyAuthenticity(document)`** runs the checks of `verifyCredential` in the same
+  order except `not_yet_valid` and `expired`: shape, version, schema, issuer, proof
+  profile, both signature halves, a validity interval, holder key, rules, level and
+  trusted status list. Its result is an `AuthenticCredential`, a provenance record of
+  its own kind: `facts`, `standing` and `checkStatus` refuse it, and so does everything
+  in ARIA AP that admits or signs.
+- **`readRetainedStatus(credential, list)`** reads a retained list offline, as
+  `checkStatus` reads a fetched one (issuer, the exact list the credential names, both
+  signatures, the supported subject, at most 24 hours of validity), but never judges its
+  times against now: it reports them. A `RetainedStatus` is not status evidence.
+- **`historicalFacts(credential, status?)`** is the read path, like `facts`: binding,
+  DID, holder key bytes, validity, and what the retained list said. It refuses anything
+  this verifier did not produce and a retained status about another document.
+
+```ts
+const authentic = verifier.verifyAuthenticity(retainedDocument);
+if (authentic.ok) {
+  const read = await verifier.readRetainedStatus(authentic.credential, retainedList);
+  // ARIA AP: ap.verifyHistoricalReceipt(receipt, { attempts, evidence: { credential: authentic.credential, status } })
+}
+```
+
+## `did:aria` identifiers
+
+`parseDid(value)` returns the parts of a `did:aria` identifier, or `null`: one of the
+four shapes of specification §3.1 (`agent-domain-form`, `agent-registry-form`,
+`principal-domain-form`, `principal-registry-form`), with its domain or registry host,
+account and agent name. It applies the same rules as the authority's parser and passes
+the 22 shared cases in `conformance/vectors/abnf-cases.json`. Use it for identifiers being
+created or compared; verifying a credential does not apply it, since a signed 1.0
+document is read under its own schema.
+
+## Credential profile
+
+`spec_version` `"1.0"` (`schema/aid-1.0.json`, embedded byte for byte and checked by a
+test) is the supported profile. Its holder key is 32 raw Ed25519 bytes under
+`Ed25519VerificationKey2020` — ARIA's own encoding, `z` and base58btc of the raw
+key, not the Multikey one; the SDK decodes exactly 32 bytes and projects `0xed01` only
+when producing a Multikey. The proof metadata is outside the signed bytes: the SDK requires the supported
+values, which does not make them signed. The suite is kept for 1.0: the dates that count are
+the signed `validFrom` and `validUntil`, not `proof.created`.
+
+## Package and runtimes
+
+- ESM only, with type declarations; `exports` has the package entry, `package.json`, and
+  `schemas/aid-1.0.json`, a byte-identical copy of the protocol's schema, so that schemas
+  referring to it (ARIA AP's identity response) compile outside this repository.
+  The dependencies are `@noble/curves`, `@noble/hashes`, `@noble/post-quantum`, `ajv` and
+  `ajv-formats`.
+- Node.js 20 and 22: everything (declared; the artifact check in
+  [`../scripts/check-pair.mjs`](../scripts/check-pair.mjs) runs on the Node.js it is given).
+- Browsers and edge runtimes: offline credential checks, with two limits: the schema
+  validator compiles code at run time, which a strict Content Security Policy forbids,
+  and network status checks there cannot enforce private-network restrictions.
+
+The package has no install scripts and reads no environment file.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/MIGRATION.md

@@ -0,0 +1,86 @@
+# From `@aria-registry/verify` 1.x to the ARIA SDK 1.0 and ARIA AP
+
+`@aria-registry/verify` 1.x is replaced by two packages in the same repository:
+
+- **the ARIA SDK** (this package, `@trustlayer-foundation/aria-sdk`) for credentials
+  and their status;
+- **ARIA AP** (`@trustlayer-foundation/aria-ap`, [`../aria-ap-ts`](../aria-ap-ts/README.md))
+  for authenticating requests, admitting them and receipts. It builds on the ARIA SDK's
+  verifier.
+
+A credential-only consumer migrates to the first; a consumer that decides whether an
+agent may do something needs both. `@aria-registry/verify` 1.x is no
+longer served by npm; its source stays in `sdk/verify-ts/` for reference.
+
+## The one change that matters
+
+```ts
+// 1.x
+const result = verifyAgent(credential, { policy });
+if (result.valid) execute();
+```
+
+`valid` could be `true` with the signature check skipped, with the requested policy
+failed, with the status never checked, and with nobody proving the holder key. It was
+never a decision to run anything, and there is no compatibility wrapper that keeps it.
+
+```ts
+// 1.0: authenticate, then admit; only `allow` runs
+const verifier = createVerifier({ trust });           // @trustlayer-foundation/aria-sdk
+const ap = createAp({ credentials: verifier });       // @trustlayer-foundation/aria-ap
+const presented = await ap.verifyPresentation(request, context);
+if (!presented.ok) return presented.status;
+const status = await verifier.checkStatus(presented.presentation.credential);
+const admission = await ap.admit({ presentation: presented.presentation, status, authorize });
+if (admission.decision !== 'allow') return admission.refusal.status;
+await execute();
+```
+
+An operation that must happen once, or that the caller needs a receipt for, runs
+through ARIA AP's `OperationLedger` (see `../aria-ap-ts/examples/protected-handler.ts`).
+
+A consumer that only displays or records whether a credential is genuine and current
+uses `verifyCredential`, `checkStatus` and `standing` (see `examples/verify-credential.ts`),
+and must not treat the answer as permission to act.
+
+## Field by field
+
+| 1.x | 1.0 |
+|---|---|
+| `verifyAgent(c)` | `createVerifier({ trust }).verifyCredential(c)`; status and admission are separate calls |
+| `verifyAgent(c, { skipSignatureCheck: true })` | `inspectCredential(c)`: returns an `Inspection`, never a verified result |
+| `setRegistryKeys(...)`, embedded registry keys | `createVerifier({ trust: [profile] })`: explicit, per verifier, nothing global or embedded |
+| `result.valid` | `CredentialResult.ok` for the document only; `standing(...).state === 'good'` for now; ARIA AP's `Admission.decision === 'allow'` to run |
+| `result.reason` (free text) | fixed reasons: `CredentialFailure`, `StatusUnavailable`, standing states; in ARIA AP, `RequestInvalidReason`, `AuthenticationReason`, `AdmissionReason` |
+| `result.signatures.pqValid/classicalValid` | both required; a failure is `signature_invalid` |
+| `result.expired` | `not_yet_valid`, `expired` or `invalid_validity`, with strict instants |
+| `result.issuedAt` | `validFrom` (signed, RFC 3339 string). There is no issuance time: `proof.created` is not signed |
+| `result.expiresAt` | `validUntil` |
+| `result.credentialId`, `previousCredentialId` | `credential.binding.credentialId`; `credential.previousCredentialId` as data, never fetched |
+| `result.revocationStatus`, `revocationCheckedAt` | `checkStatus(credential)` → `StatusEvidence` with source, signed list times and `fetchedAt` |
+| `checkRevocation(did)` | removed: it asked about a DID, not the presented document |
+| `checkCredentialStatus(c, { via })` | `checkStatus(credential, { via: 'status-list' \| 'online' })`; the online endpoint is the profile's `onlineStatus` |
+| `policy.requiredScopes`, `minTrustLevel` | ARIA AP: `OperationDescriptor.scope`, `minLevel`, enforced by `admit` |
+| `policy.requireRevocationCheck`, `lastRevocationCheck`, `maxOfflineAge` | `statusMaxAgeSeconds`, from the signed list's `validFrom`, judged by `standing` at use; a fresh fetch time is not evidence |
+| `result.hitlRequired` | `credential.hitlRequired`, a declaration; the approval is ARIA AP's `ApprovalEvidence` at `admit` |
+| `PolicyLevel` presets | none: each operation states its level and scope |
+| `canonicalJson` | `canonicalJson`, the ARIA canonical form (INVARIANTS §3) |
+| results as plain objects you could copy or edit | frozen views the producing verifier recognises by identity; copies and other verifiers' results throw `AriaUsageError` |
+
+## What the old characterizations become
+
+The 1.x probes recorded behaviors; they are not all defects. In the 1.0 tests:
+
+- **kept as controls**: a valid baseline passes schema and both signatures; altered signed
+  content and an expired credential are refused;
+- **turned into rejections**: not-yet-valid, invalid or inverted validity bounds, a
+  missing holder key, the skipped signature check (now inspection only), a failed
+  requested scope (now an ARIA AP `deny`), a revoked status discarded by the old recipe
+  (now `revoked` standing and an ARIA AP `deny`), unsupported proof metadata (refused,
+  still unsigned);
+- **checked at their own layer**: a copied credential still verifies as a document but
+  cannot be admitted without its holder key; offline verification succeeds with unknown
+  status and an `unknown` standing, while an ARIA AP admission that needs status is
+  `indeterminate`;
+- **schema versus rules**: the schema alone accepts `hitlRequired` outside `scope`; the
+  SDK refuses it as `semantic_invalid`.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# ARIA SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@trustlayer-foundation/aria-sdk` verifies an AI agent's ARIA credential (AID 1.0) and the
+status of that exact document, under the issuers you choose to trust. It is the
+TypeScript SDK of [ARIA 1.0](https://aria.bar/spec), for Node.js 20 or later, published by
+TrustLayer Foundation under Apache-2.0.
+
+## Which package do I need?
+
+| You want to | Install |
+|---|---|
+| Show or record whether an agent's credential is genuine, current and not revoked | `@trustlayer-foundation/aria-sdk` |
+| Decide whether an agent's request may run: authenticate it, admit it, run the operation once and sign its receipt; or call such a service as an agent | `@trustlayer-foundation/aria-sdk` and [`@trustlayer-foundation/aria-ap`](https://github.com/trustlayer-foundation/aria-protocol/tree/main/sdk/aria-ap-ts#readme) |
+
+```bash
+npm install @trustlayer-foundation/aria-sdk
+```
+
+[ARIA AP](https://github.com/trustlayer-foundation/aria-protocol/tree/main/sdk/aria-ap-ts#readme)
+builds on this package's verifier and has no credential verification of its own. It
+declares this package as a peer dependency, so a service that uses both installs both:
+`npm install @trustlayer-foundation/aria-sdk @trustlayer-foundation/aria-ap`.
+
+## Quick start
+
+The SDK trusts no issuer by default. You state each issuer you accept in a trust profile.
+Today's issuer, `did:aria:registry.aria.bar` behind [agent.bar](https://agent.bar), is a
+demonstration: its credentials are not a production guarantee, and production ARIA 1.0
+will use a new TrustLayer Foundation issuer and keys. It serves its keys at
+`https://api.aria.bar/v1/keyset`. Being listed there grants no trust: you pin the anchor
+fingerprint you obtained out of band, from the
+[release manifest](https://github.com/trustlayer-foundation/aria-protocol/blob/main/release/aria-1.0.json),
+and take the key it names. Save this as `quickstart.mjs` and run it with `node
+quickstart.mjs`:
+
+```javascript
+import { canonicalJson, createVerifier } from '@trustlayer-foundation/aria-sdk';
+
+/** A verifier trusting the key, in an issuer's published key set, that `pinned` names. */
+export async function verifierFromKeyset({ keysetUrl, pinned, profile, fetch = globalThis.fetch }) {
+  const keyset = await (await fetch(keysetUrl, { redirect: 'error' })).json();
+  const entry = keyset.keys.find((k) => k.fingerprint === pinned && k.active_until === null);
+  if (!entry) throw new Error('the key set holds no active key with the pinned fingerprint');
+  const identity = canonicalJson({
+    key_id: entry.key_id,
+    suite: entry.suite,
+    public_key_mldsa65: entry.public_key_mldsa65,
+    public_key_ed25519: entry.public_key_ed25519,
+  });
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(identity));
+  if (`sha256:${Buffer.from(digest).toString('hex')}` !== pinned) throw new Error('the pinned key does not match');
+  return createVerifier({
+    ...profile.verifier, // clock, fetch policy
+    trust: [{
+      id: profile.id, // 'demo' or 'production': your statement, not the issuer's
+      issuer: keyset.issuer,
+      verificationMethod: entry.key_id,
+      keys: { mldsa65: Buffer.from(entry.public_key_mldsa65, 'hex'), ed25519: Buffer.from(entry.public_key_ed25519, 'hex') },
+      maxLevel: profile.maxLevel,
+      statusLists: profile.statusLists,
+    }],
+  });
+}
+
+const verifier = await verifierFromKeyset({
+  keysetUrl: 'https://api.aria.bar/v1/keyset',
+  pinned: 'sha256:4117aaac21272740756d02305a9fa7e2d84398fdd859d390b476539d57ec67b3',
+  profile: {
+    id: 'demo',
+    maxLevel: 'L1',
+    statusLists: ['https://api.aria.bar/v1/status/1'],
+    verifier: { fetch: { allowedOrigins: ['https://api.aria.bar'] } },
+  },
+});
+
+const credential = await (await fetch('https://api.aria.bar/v1/aids/did:aria:aria.bar:u-0dhNSrC9:commerce-search')).json();
+const result = verifier.verifyCredential(credential);
+if (!result.ok) throw new Error(`credential refused: ${result.reason}`);
+const status = await verifier.checkStatus(result.credential);
+const standing = verifier.standing(result.credential, status);
+console.log(result.credential.did, result.credential.trustLevel, status.state, standing.state);
+```
+
+It prints the agent's DID, its level, `active` and `good`. Alter one byte of either
+signature half and `verifyCredential` refuses it with `signature_invalid`; pin another
+fingerprint and the function throws.
+
+## Trust is your configuration
+
+A verifier trusts exactly the profiles it is created with. There is no global setting and
+no embedded key. A profile states:
+
+| Field | What you state |
+|---|---|
+| `id` | Your name for this trust, such as `demo` or `production` |
+| `issuer` | The issuer's DID |
+| `verificationMethod` | The key id its proofs name, such as `did:aria:registry.aria.bar#key-1` |
+| `keys` | Its two public keys, ML-DSA-65 and Ed25519, as bytes |
+| `maxLevel` | The highest level you accept from it; a credential claiming more is refused |
+| `statusLists` | The status lists it publishes; a credential naming another is refused |
+| `onlineStatus` | Optional: an online status endpoint, asked only when you request it |
+
+The fetch policy (`fetch.allowedOrigins`, timeouts, size bounds) bounds everything the SDK
+fetches, and redirects are never followed. Without one, the verifier is offline and status
+is `unavailable`. Credentials, status lists and online answers are untrusted input: nothing
+in them selects a trust anchor or a fetch target.
+
+## What each result tells you
+
+| Call | Establishes | Does not establish |
+|---|---|---|
+| `verifyCredential(document)` returns `{ ok: true, credential }` or `{ ok: false, reason }` | The AID 1.0 schema; an issuer your profile names; the proof profile; both halves of the composite signature (ML-DSA-65 and Ed25519) over the canonical document; the signed validity window; the holder key; a level within your `maxLevel`; a status list in your `statusLists` | Who presents the credential; its status |
+| `checkStatus(credential)` returns status evidence | The status of that exact document: `active` or `revoked` from the signed status list it names, verified under the same profile and fresh enough, or `unavailable` with a reason | Anything about another document of the same DID |
+| `standing(credential, status)` | Whether that document stands now: `good`, `revoked`, `superseded`, `not_valid_now` or `unknown` | That anyone presents it, or may do anything with it |
+| `inspectCredential(document)` | The fields a document carries, for display; `verified` is always `false` | Anything verified |
+
+None of these results is permission to act. Whether an agent may do something is
+decided by ARIA AP's admission, after the agent proves possession of its holder key.
+`unknown` is not `good`. The SDK verifies credentials you hold; it is not a DID resolver.
+
+## Documentation
+
+- [API contract](https://github.com/trustlayer-foundation/aria-protocol/blob/main/sdk/aria-ts/API.md):
+  every result, failure reason, the trust boundary, status and historical authenticity.
+- [Example: checking a credential and its standing](https://github.com/trustlayer-foundation/aria-protocol/blob/main/sdk/aria-ts/examples/verify-credential.ts).
+- [Migration from `@aria-registry/verify` 1.x](https://github.com/trustlayer-foundation/aria-protocol/blob/main/sdk/aria-ts/MIGRATION.md),
+  which is no longer served by npm.
+- [ARIA AP](https://github.com/trustlayer-foundation/aria-protocol/tree/main/sdk/aria-ap-ts#readme),
+  for requests, admission and receipts.
+- [Developer guide](https://aria.bar/developers) and
+  [specification](https://aria.bar/spec).
+- [Release manifest](https://github.com/trustlayer-foundation/aria-protocol/blob/main/release/aria-1.0.json):
+  the package integrities and the demonstration issuer's anchor.
+- [Conformance vectors](https://github.com/trustlayer-foundation/aria-protocol/tree/main/conformance),
+  for any implementation.
+
+## Support
+
+- Questions and bugs:
+  [GitHub issues](https://github.com/trustlayer-foundation/aria-protocol/issues).
+- Security vulnerabilities: security@trustlayer.foundation, never a public issue
+  ([security policy](https://github.com/trustlayer-foundation/aria-protocol/blob/main/SECURITY.md)).
+
+## Development
+
+In the [repository](https://github.com/trustlayer-foundation/aria-protocol):
+- `pnpm typecheck` compiles the sources, examples, tests and boundary checks.
+- `pnpm test` runs the tests, with synthetic issuer keys made per run.
+- `pnpm build` writes `dist/`.
+- `node ../scripts/check-pair.mjs` packs this package and ARIA AP and checks both as
+  installed artifacts, alone and together.
+
+The README that npm shows for a version is the one packed in it; this file is newer than
+1.0.0's.