@numerum-tech/yeriasdk 1.0.0

package/dist/core/jsonapp.d.ts

@@ -0,0 +1,263 @@
+import { BaseView } from './base-view';
+import { FormView } from './form-view';
+import { ReaderView } from './reader-view';
+import { ActionListView } from './action-list-view';
+import { ActionGridView } from './action-grid-view';
+import { QRScanView } from './qr-scan-view';
+import { QRDisplayView } from './qr-display-view';
+import { MessageView } from './message-view';
+import { CardView } from './card-view';
+import { CarouselView } from './carousel-view';
+import { TimelineView } from './timeline-view';
+import { MediaView } from './media-view';
+import { MapView } from './map-view';
+import { Notification } from './notification';
+import { SecureNotificationResponse } from '../types';
+export interface JsonAppConfig {
+    appId: string;
+    privateKey?: string;
+    publicKey?: string;
+    allowedDomains?: string[];
+    viewExpirationMinutes?: number;
+    platformUrl?: string;
+    notificationTimeout?: number;
+}
+/**
+ * What `serve()` returns. The whole object goes on the wire as a JSON
+ * envelope — `res.json(jsonApp.serve(view))`. The signature CANNOT be
+ * forgotten because it lives in the structure itself, not in a header.
+ *
+ * `payload` is a JSON string (already serialised) — it's the bytes that
+ * were signed. The renderer verifies the signature on those exact bytes,
+ * then JSON.parses `payload` to get the decoded view envelope. No
+ * re-stringification happens on either side, so JS and Dart can't drift
+ * on JSON encoding.
+ */
+export interface SignedEnvelope {
+    /** JSON string of `{appId, timestamp, view}` — the bytes that were signed. */
+    payload: string;
+    /** Ed25519 signature over `payload` (base64). */
+    signature: string;
+}
+/** Decoded inner payload — the parsed shape of `payload`. */
+export interface DecodedPayload {
+    appId: string;
+    timestamp: number;
+    view: Record<string, unknown>;
+}
+/**
+ * Claims surfaced by `verifyUserToken` after a successful RS256 check.
+ * Mirrors the fields Yeria puts in a per-service JWT.
+ */
+export interface UserTokenClaims {
+    /** Yeria user id. */
+    sub: string;
+    /** Either `'yeria-admin'` for the platform token, or the service id (as string) for a service-scoped token. */
+    aud: string;
+    /** Issuer — always `'yeria'`. */
+    iss: string;
+    /** Expiration time (unix seconds). */
+    exp: number;
+    /** Issued-at time (unix seconds). */
+    iat?: number;
+    /** Key id from the JWT header (`kid`). Useful for key-rollover scenarios. */
+    kid?: string;
+}
+/**
+ * Resolver passed to `verifyUserTokenWithResolver`. Given the `kid` from
+ * the JWT header, returns the PEM the SDK should verify against — or
+ * `null` when the key is expired / unknown / not yet propagated. Wraps
+ * whatever lookup strategy the caller wants (typically `YeriaKeyStore`).
+ */
+export type YeriaPublicKeyResolver = (kid: string) => Promise<string | null>;
+/**
+ * Projection returned by `JsonApp.fetchUserProfile`. The current Yeria
+ * scope is intentionally minimal; the per-service `service_access.profile_scopes`
+ * work will widen this set without changing the field names.
+ */
+export interface UserProfile {
+    user_id: number;
+    first_name: string | null;
+    last_name: string | null;
+    country_code: string | null;
+}
+export declare class JsonApp {
+    private config;
+    private privateKey;
+    private publicKey;
+    constructor(config: JsonAppConfig);
+    /**
+     * Crée une vue de formulaire sécurisée
+     */
+    createFormView(formId: string, title: string, processId?: string): FormView;
+    /**
+     * Crée une vue de lecture sécurisée
+     */
+    createReaderView(viewId: string, title: string, processId?: string): ReaderView;
+    /**
+     * Crée une vue de liste d'actions sécurisée
+     */
+    createActionListView(viewId: string, title: string, processId?: string): ActionListView;
+    /**
+     * Crée une vue de grille d'actions sécurisée
+     */
+    createActionGridView(viewId: string, title: string, processId?: string): ActionGridView;
+    /**
+     * Crée une vue de scan QR sécurisée
+     */
+    createQRScanView(viewId: string, title: string, processId?: string): QRScanView;
+    /**
+     * Crée une vue d'affichage QR sécurisée
+     */
+    createQRDisplayView(viewId: string, title: string, processId?: string): QRDisplayView;
+    /**
+     * Crée une vue de message sécurisée
+     */
+    createMessageView(viewId: string, title: string, processId?: string): MessageView;
+    createCardView(viewId: string, title: string, processId?: string): CardView;
+    createCarouselView(viewId: string, title: string, processId?: string): CarouselView;
+    createTimelineView(viewId: string, title: string, processId?: string): TimelineView;
+    createMediaView(viewId: string, title: string, processId?: string): MediaView;
+    createMapView(viewId: string, title: string, processId?: string): MapView;
+    /**
+     * Crée une notification pour un utilisateur spécifique
+     */
+    createNotification(userId: string, title: string, body: string, link?: string): Notification;
+    /**
+     * Signe une notification avec Ed25519
+     */
+    signNotification(notification: Notification): SecureNotificationResponse;
+    /**
+     * Envoie une notification signée à la plateforme City-Mate
+     * @param notification - Notification à envoyer
+     * @param platformUrl - URL de la plateforme (optionnel, utilise config.platformUrl si non fourni)
+     * @throws {ConfigurationError} Si aucune URL de plateforme n'est configurée
+     * @throws {ExternalError} Si l'envoi échoue
+     */
+    sendNotification(notification: Notification, platformUrl?: string): Promise<void>;
+    /**
+     * Rotate the service's signing key on the Yeria registry. The rotation
+     * envelope is signed with the *current* private key — the caller proves
+     * they own the still-valid keypair before the new one is accepted.
+     *
+     * After this call succeeds:
+     *   - The new public key becomes Active on Yeria.
+     *   - The old key keeps validating signatures for ~5 minutes (grace
+     *     window so in-flight signed responses still verify).
+     *   - This JsonApp instance is mutated to use the new keypair locally.
+     *
+     * @param yeriaApiBaseUrl - Yeria registry root, e.g. `https://yeria.app`
+     * @param serviceId       - The service id assigned by Yeria
+     * @param newKeys         - The freshly-generated keypair to switch to
+     */
+    rotateKey(yeriaApiBaseUrl: string, serviceId: string | number, newKeys: {
+        privateKey: string;
+        publicKey: string;
+    }): Promise<{
+        keyId: number;
+        expiresAt: string;
+        gracePeriodMinutes: number;
+    }>;
+    /**
+     * Sérialise une vue, signe les bytes sérialisés, et retourne une
+     * enveloppe `{payload, signature}` à envoyer telle quelle au client.
+     *
+     * Usage côté provider (Express) :
+     *   res.json(jsonApp.serve(view));
+     *   res.status(400).json(jsonApp.serve(errorMessage));
+     *
+     * La signature est dans la structure de retour — impossible de
+     * l'oublier en l'envoyant. Le client vérifie sur `payload` (string)
+     * sans re-stringification.
+     */
+    serve(view: BaseView): SignedEnvelope;
+    /**
+     * Obtient la clé publique pour la vérification côté frontend
+     */
+    getPublicKey(): string;
+    /**
+     * Vérifie l'intégrité d'une enveloppe signée reçue du wire.
+     *
+     * @throws {AppIdMismatchError}        si appId ne matche pas this.config.appId
+     * @throws {ViewExpiredError}          si timestamp > viewExpirationMinutes
+     * @throws {SignatureVerificationError} si signature invalide ou payload malformé
+     */
+    verifyIntegrity(envelope: SignedEnvelope): boolean;
+    /**
+     * Méthode statique pour vérifier une signature.
+     * @param publicKey - Clé publique Ed25519 (PEM format)
+     * @param payload   - JSON string signée (extraite de l'enveloppe)
+     * @param signature - Signature base64
+     * @param onError   - Optional error callback for logging
+     * @returns true si la signature est valide
+     */
+    static verifySignature(publicKey: string, payload: string, signature: string, onError?: (error: Error) => void): boolean;
+    /**
+     * Génère statiquement une enveloppe signée sans instance JsonApp.
+     */
+    static signView(view: Record<string, unknown>, appId: string, privateKey: string, timestamp?: number): SignedEnvelope;
+    /**
+     * Verify a Yeria-issued user token (RS256 JWT signed by Yeria's
+     * Registry RSA key). Used by providers to authenticate inbound
+     * requests carrying `Authorization: Bearer <serviceToken>`.
+     *
+     * @param jwtToken           Compact JWT (header.payload.signature, base64url).
+     * @param yeriaPublicKey     Yeria's Registry public key in PEM format.
+     *                           Fetch once at boot from
+     *                           `GET /api/v1/registry/public-key` and cache.
+     * @param expectedServiceId  When supplied, asserts `aud === String(expectedServiceId)`.
+     *                           Pass the service id your backend is hosting; refuse
+     *                           tokens scoped to a different service.
+     * @returns                  The verified claims object.
+     * @throws SignatureVerificationError if signature invalid / token malformed / wrong issuer / wrong audience.
+     * @throws ViewExpiredError            if the `exp` claim is in the past.
+     */
+    static verifyUserToken(jwtToken: string, yeriaPublicKey: string, expectedServiceId?: string | number): UserTokenClaims;
+    /**
+     * Same audience-scoped JWT verify as `verifyUserToken`, but the second
+     * argument is a kid resolver instead of a fixed PEM. The SDK pulls
+     * the `kid` from the JWT header, calls `resolver(kid)`, and verifies
+     * the signature against whatever PEM comes back.
+     *
+     * Pair with `YeriaKeyStore` so providers don't have to write key-
+     * fetching, caching or rotation-grace handling themselves.
+     *
+     * @throws SignatureVerificationError if the resolver returns null, the
+     *         signature fails, the issuer / audience mismatches, or the
+     *         JWT is malformed.
+     * @throws ViewExpiredError when `exp` is in the past.
+     */
+    static verifyUserTokenWithResolver(jwtToken: string, resolver: YeriaPublicKeyResolver, expectedServiceId?: string | number): Promise<UserTokenClaims>;
+    /**
+     * Provider-side helper: fetch a Yeria user's profile by `sub`.
+     *
+     * Builds an Ed25519-signed envelope and POSTs to
+     * `POST /api/v1/provider/services/{serviceId}/users/{userId}/profile`.
+     * Yeria already holds every Active public key for this service, so
+     * the envelope itself is the only credential — no user JWT is sent
+     * in the body and the PEM is never disclosed.
+     *
+     * Typical usage (provider middleware after `verifyUserTokenWithResolver`):
+     *
+     *   let user = await db.users.findByYeriaSub(claims.sub);
+     *   if (!user) {
+     *     const profile = await JsonApp.fetchUserProfile({
+     *       baseUrl: process.env.YERIA_BASE_URL,
+     *       serviceId: MY_SERVICE_ID,
+     *       userId: claims.sub,
+     *       privateKey: SERVICE_ED25519_PRIVATE_KEY,
+     *     });
+     *     user = await db.users.insert({ yeria_sub: claims.sub, ...profile });
+     *   }
+     *
+     * The hot path stays local-DB after the first miss.
+     */
+    static fetchUserProfile(opts: {
+        baseUrl: string;
+        serviceId: string | number;
+        userId: string | number;
+        privateKey: string;
+        fetch?: typeof fetch;
+    }): Promise<UserProfile>;
+}
+//# sourceMappingURL=jsonapp.d.ts.map

package/dist/core/jsonapp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonapp.d.ts","sourceRoot":"","sources":["../../src/core/jsonapp.ts"],"names":[],"mappings":"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"}