The cardano.tech gateway is the private hosted-service core for reusable Cardano capabilities across foss.global products. Its first module provides authenticated, multi-tenant Wallet Proof orchestration over the public @cardanotech/interfaces and @cardanotech/walletproof contracts.

This repository currently contains the in-process core, SmartData/MongoDB persistence adapter, and a provider-neutral transport adapter. It deliberately does not start a network listener, provision or validate workload credentials, or bind itself to TypedServer or serve.zone.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Trust boundary

WalletProofGatewayCore accepts an already-authenticated IGatewayExecutionContext. WalletProofGatewayTransportAdapter<TTransportContext> requires an injected IWorkloadContextResolver<TTransportContext> to derive that context from transport state owned by the hosting application.

The context provides:

request, workload, and tenant identifiers;
issuer and audience;
Wallet Proof permissions;
allowed origins, networks, and purposes.

The core validates and deep-copies the complete context before its first asynchronous operation. Tenant, workload, permissions, and policy are never taken from the public Wallet Proof request DTOs.

The adapter owns a private TypedRouter for exactly createWalletProofChallenge, completeWalletProofChallenge, and getWalletProofReceipt. Before that router sees a request, the adapter reconstructs the exact supported request envelope and method-specific leaf DTO from allowlisted fields. Caller-supplied local data, trusted-local-data lookalikes, and unrelated metadata are discarded. The required correlation ID is the sole caller metadata preserved; it is bounded and rejects surrounding whitespace and control characters. Only the resolver-produced execution context is supplied as TypedRequest trustedLocalData, and private dispatch uses skipHooks so global request/response hooks cannot observe proof payloads. The router is not exposed. This adapter remains a gateway-package composition primitive rather than a shared transport contract or consumer SDK.

Structured failures are reduced to the public safe error shape before crossing the adapter boundary. Every call returns a newly reconstructed response envelope; it does not echo the input request, proof, caller metadata other than the validated correlation ID, or transport context. Unknown failures do not expose stack traces, causes, credential material, transport state, or internal error details.

There is intentionally no bearer parser, JWT convention, shared-secret header, OAuth client_credentials flow, browser credential, TypedServer, listener, serve.zone capability, or platform binding in this repository yet. Credential provisioning, validation, rotation, expiry, and revocation belong to a separately reviewed hosted admission layer.

The adapter does not open sockets, accept credentials, retry requests, or own the core lifecycle. The composition root remains responsible for starting and stopping the core and for the lifecycle of its transport resources.

Persistence

MongoGatewayStore uses an initialized @push.rocks/smartdata SmartdataDb and creates exact MongoDB indexes for:

tenant- and workload-scoped challenges;
atomic pending/verifying claim and lease recovery;
tenant- and workload-scoped receipt lookup;
idempotency keys scoped by tenant, workload, issuer, audience, method, and key;
safe audit lookup.

Challenge claims and idempotency operations use compare-and-set transitions with attempt-specific lease tokens. Stale tokens cannot terminalize a reclaimed operation. Idempotency scope includes tenant, workload, issuer, audience, method, and key, and its lease must outlive the bounded Wallet Proof verification lease. State-dependent claim, terminal, and lease fields are removed with $unset; they are absent in BSON when inactive rather than stored as null.

The injected SmartdataDb owns its connection lifecycle. The gateway core creates indexes during start() and waits for every index operation to settle before reporting initialization failure, but does not close the injected database during stop(). stop() first rejects new calls, drains active operations, and only then zeroes its copied secrets. Each short-lived Wallet Proof service is disposed in finally. An initialization failure or initialization interrupted by stop() is terminal and zeroes the core secrets rather than making a zeroed core appear started. There is no filesystem persistence fallback.

Core usage

import {
  MongoGatewayStore,
  WalletProofGatewayCore,
  type IGatewayExecutionContext,
} from '@cardanotech/gateway';
import type { SmartdataDb } from '@push.rocks/smartdata';

declare const smartdataDb: SmartdataDb;
declare const bindingSecret: Uint8Array;
declare const operationSecret: Uint8Array;
declare const authenticatedContext: IGatewayExecutionContext;

const core = new WalletProofGatewayCore({
  store: new MongoGatewayStore(smartdataDb),
  bindingSecret,
  operationSecret,
});

await core.start();

const { challenge } = await core.createWalletProofChallenge(
  authenticatedContext,
  {
    subjectRef: 'opaque-consumer-subject',
    origin: 'https://app.example',
    network: 'testnet',
    purpose: 'link-wallet',
    idempotencyKey: 'wallet-link-create-0001',
  },
);

await core.stop();

Both secrets must contain at least 32 random bytes and come from an injected managed-secret boundary. They are copied on construction and zeroed when the core stops. They must never be committed, logged, placed in SmartData, or returned in a DTO.

Transport adapter usage

import {
  WalletProofGatewayTransportAdapter,
  type IWorkloadContextResolver,
  type WalletProofGatewayCore,
} from '@cardanotech/gateway';

interface ITrustedTransportContext {
  admissionReference: string;
}

declare const core: WalletProofGatewayCore;
declare const contextResolver: IWorkloadContextResolver<ITrustedTransportContext>;
declare const requestEnvelope: unknown;
declare const trustedTransportContext: ITrustedTransportContext;

const adapter = new WalletProofGatewayTransportAdapter({
  core,
  contextResolver,
});

const responseEnvelope = await adapter.route(
  requestEnvelope,
  trustedTransportContext,
);

The optional requestIdFactory constructor dependency is available to the composition root. The supplied transport context must come from the hosting application's trusted admission path; it is never reconstructed from the public request envelope.

Recovery and privacy

Subject identifiers, challenge identifiers, nonces, receipt identifiers, and request digests use separate domain-separated HMAC derivations. A create operation reclaimed after its original expiry cannot create a newly expired challenge. Receipt recovery succeeds only when the persisted receipt ID matches the exact tenant/workload/idempotency operation and request digest; a different idempotency key remains a replay.

Audit records contain only workload, tenant, action, outcome, request/target references, timestamps, and safe error codes. They exclude raw addresses, signatures, COSE keys, challenge messages, secrets, and identity data. Successful receipts are also privacy-safe and exclude the raw proof.

Development

pnpm install
pnpm run build
pnpm test
pnpm run test:mongo
tsbuild check 'test/**/*' --skiplibcheck

pnpm test runs the in-process authorization, policy, idempotency, recovery, context-snapshot, lifecycle, redaction, and transport-boundary coverage together with the disposable SmartMongo suite. The Mongo suite verifies real index, BSON, concurrency, lease, reconciliation, expiry, strict runtime timestamp/discriminant validation, and cross-workload behavior. Its registered post-task closes SmartData and attempts replica-set shutdown through a guarded finally path even after test failures. pnpm run test:mongo remains available for the focused persistence suite.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

cardano.tech gateway