SDK & tools

Everything you need to implement and test the Connect v1 contract. Correctness does not depend on your language: the same signature test vectors and the same conformance test apply to every app.

#@cosuite/connect (Node.js)

The reference implementation of the contract for Node.js 18.17+, written in TypeScript. MIT license.

npm install https://cosuite.io/developers/sdk/cosuite-connect-1.8.0.tgz

The package installs as @cosuite/connect, so imports stay the same. It will also be published to the npm registry; until then install it from this address.

handleConnectRequest works with the web-standard Request and Response, so it runs as is in Next.js route handlers, Hono, Bun or Deno, and with a small bridge in Express or Fastify. See the 10-minute quick start for a full route.

#Verifying SSO

import { createSsoVerifier, MemoryReplayStore } from "@cosuite/connect";

const verifySso = createSsoVerifier({
  issuer: "https://cosuite.io",
  audience: "dent", // your app key
  jwksUrl: "https://api.cosuite.io/connect/v1/jwks.json",
  replay: new MemoryReplayStore(),
});

// POST /api/cosuite/v1/sso, form field "token"
const claims = await verifySso(token); // throws ConnectError when invalid, expired or reused
// claims.sub, claims.tid, claims.email, claims.role, claims.redirect …

#Sending events

import { CoSuiteClient } from "@cosuite/connect";

const cosuite = new CoSuiteClient({
  baseUrl: "https://api.cosuite.io/connect/v1",
  keyId: process.env.COSUITE_KEY_ID!,
  secret: process.env.COSUITE_CONNECT_SECRET!,
});

await cosuite.sendEvent({
  id: "evt_01J9ZK3Q", // stable id from your outbox; also used as the request id
  type: "usage.threshold_reached",
  tenantId: "org_8f2c",
  occurredAt: new Date().toISOString(),
  data: { metric: "smsPerMonth", percent: 80 },
});

#Conformance test

The conformance test connects to your app's URL and exercises the contract end to end. It does not care which language your app is written in. CoSuite runs it before your app goes live and you should run it in your CI against staging: if it is red, do not release.

export COSUITE_CONNECT_SECRET=…   # the secret of the key you test with; never put it on the command line
npx --yes --package=https://cosuite.io/developers/sdk/cosuite-connect-1.8.0.tgz cosuite-connect conformance --url https://staging.dentcloud.example --key csk_dent_test

It runs these checks in order:

1. manifest and health;
2. module definition (contract 1.7, only the fields you fill in), including downloading and checking each OpenAPI document;
3. signature attacks: unsigned, expired timestamp, unknown key, changed body, changed method;
4. opening a tenant with test: true, request-id replay (same body returns the first response, different body is 409), idempotent re-open, unknown link code is 409 invalid_link_code, unknown tenant 404, invalid body 400, PATCH;
5. entitlement versions: 2, then 1 (must not apply), the same 2 again (must not apply), then 3 with an unknown module and field (must be ignored), then read back;
6. adding, listing and removing members;
7. customers (if you declare customers): page shape, invalid limit and cursor;
8. usage and summary, including the 1-second summary budget and the 6-card maximum;
9. SSO (with --sso-key): valid token reaches the requested page, reused token, token for another app, broken signature;
10. deleting the tenant.

The exit code is 0 when everything passes and 1 otherwise. The human-readable output currently prints its check names in Turkish and ends with YEŞİL (green) or KIRMIZI (red); use --json if you parse the result.

#Local reference app

Develop against an in-memory app that already implements the contract, or compare its behaviour with yours:

COSUITE_CONNECT_SECRET=… npx --yes --package=https://cosuite.io/developers/sdk/cosuite-connect-1.8.0.tgz cosuite-connect mock --asist dent --port 4010 --key csk_dent_dev [--single-tenant-users]

--single-tenant-users makes it behave like an app where an email can belong to only one account (409 member_conflict).

#Signature test vectors

Every implementation must produce exactly these signatures. All strings are UTF-8; the timestamp is used as written (as a decimal string).

The canonical string of the first case is:

GET|/api/cosuite/v1/manifest|1761469200|e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

The same vectors ship as test-vectors/signature.json in the @cosuite/connect package.

#Signature snippets

There is no separate package for other languages: the signature is a single function. Each snippet below was run against all four test vectors above and produces them exactly. Remember the rules around it: read the raw body bytes, verify before parsing JSON, accept at most 256 KB, keep write-request ids for 10 minutes and return the error envelope.

#.NET (C#)

using System.Security.Cryptography;
using System.Text;

public static class CoSuiteSignature
{
    public const int MaxSkewSeconds = 300;

    public static string Compute(string secret, string method, string pathAndQuery, string timestamp, byte[] body)
    {
        var bodyHash = Convert.ToHexStringLower(SHA256.HashData(body));
        var canonical = $"{method.ToUpperInvariant()}|{pathAndQuery}|{timestamp}|{bodyHash}";
        var mac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(canonical));
        return "v1=" + Convert.ToHexStringLower(mac);
    }

    /// <summary>secrets: the valid secrets for this keyId (two during key rotation).</summary>
    public static bool Verify(IReadOnlyList<string> secrets, string method, string pathAndQuery, string timestamp, byte[] body, string signature, long nowUnix)
    {
        if (!long.TryParse(timestamp, out var ts) || Math.Abs(nowUnix - ts) > MaxSkewSeconds) return false;
        if (!signature.StartsWith("v1=") || signature.Length != 67) return false;
        var given = Encoding.ASCII.GetBytes(signature);
        var match = false;
        foreach (var s in secrets)
            match |= CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(Compute(s, method, pathAndQuery, timestamp, body)), given);
        return match;
    }
}

In ASP.NET Core, call Request.EnableBuffering() and read the raw body before model binding; pathAndQuery is Request.PathBase + Request.Path + Request.QueryString. Do not return ProblemDetails from contract endpoints; use the contract's error envelope. Convert.ToHexStringLower needs .NET 9; on older versions use Convert.ToHexString(...).ToLowerInvariant().

SSO with Microsoft.IdentityModel.JsonWebTokens:

using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

var jwks = new JsonWebKeySet(await http.GetStringAsync("https://api.cosuite.io/connect/v1/jwks.json")); // cache for 1 hour
var result = await new JsonWebTokenHandler().ValidateTokenAsync(token, new TokenValidationParameters
{
    ValidIssuer = "https://cosuite.io",
    ValidAudience = "dent",                 // your app key
    IssuerSigningKeys = jwks.GetSigningKeys(),
    ValidAlgorithms = new[] { SecurityAlgorithms.EcdsaSha256 },
    ClockSkew = TimeSpan.FromSeconds(30),
    RequireExpirationTime = true,
});
// Then: reject if exp - iat > 60, keep jti for 2 minutes (single use), allow only "/path" redirects.

#PHP

PHP 8.0+ (uses only the built-in hash extension):

<?php
const COSUITE_MAX_SKEW_SECONDS = 300;

function cosuite_signature(string $secret, string $method, string $pathAndQuery, string $timestamp, string $body): string
{
    $canonical = strtoupper($method) . '|' . $pathAndQuery . '|' . $timestamp . '|' . hash('sha256', $body);
    return 'v1=' . hash_hmac('sha256', $canonical, $secret);
}

/** @param string[] $secrets the valid secrets for this keyId (two during key rotation) */
function cosuite_verify(array $secrets, string $method, string $pathAndQuery, string $timestamp, string $body, string $signature, ?int $now = null): bool
{
    $now ??= time();
    if (!ctype_digit($timestamp) || abs($now - (int) $timestamp) > COSUITE_MAX_SKEW_SECONDS) {
        return false; // 401 signature_expired
    }
    $match = false;
    foreach ($secrets as $secret) {
        $match = hash_equals(cosuite_signature($secret, $method, $pathAndQuery, $timestamp, $body), $signature) || $match;
    }
    return $match; // false -> 401 invalid_signature
}

// Usage: $body = file_get_contents('php://input'); $path = $_SERVER['REQUEST_URI'];
// cosuite_verify($secrets, $_SERVER['REQUEST_METHOD'], $path, $_SERVER['HTTP_X_COSUITE_TIMESTAMP'], $body, $_SERVER['HTTP_X_COSUITE_SIGNATURE']);

#Python

Python 3.10+ (standard library only):

import hashlib
import hmac
import time

MAX_SKEW_SECONDS = 300


def cosuite_signature(secret: str, method: str, path_and_query: str, timestamp: str, body: bytes) -> str:
    body_hash = hashlib.sha256(body).hexdigest()
    canonical = f"{method.upper()}|{path_and_query}|{timestamp}|{body_hash}"
    mac = hmac.new(secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256).hexdigest()
    return "v1=" + mac


def cosuite_verify(secrets: list[str], method: str, path_and_query: str, timestamp: str,
                   body: bytes, signature: str, now: int | None = None) -> bool:
    now = int(time.time()) if now is None else now
    if not timestamp.isdigit() or abs(now - int(timestamp)) > MAX_SKEW_SECONDS:
        return False  # 401 signature_expired
    match = False
    for secret in secrets:  # two secrets are valid during key rotation
        expected = cosuite_signature(secret, method, path_and_query, timestamp, body)
        match |= hmac.compare_digest(expected, signature)
    return match  # False -> 401 invalid_signature

Pass the raw body bytes (request.body in Django, request.get_data() in Flask) and the raw request target exactly as the client sent it (for example RAW_URI or REQUEST_URI from your WSGI server). Framework helpers that rebuild the path may decode or re-encode characters such as %3A and break the signature.

For SSO in PHP or Python, use any maintained JWT library that supports ES256 and JWKS (for example firebase/php-jwt or PyJWT with PyJWKClient) and apply the SSO checks.