{"id":29284455,"url":"https://github.com/jedisct1/zig-common-access-token","last_synced_at":"2026-03-02T08:01:49.276Z","repository":{"id":294186609,"uuid":"984658338","full_name":"jedisct1/zig-common-access-token","owner":"jedisct1","description":"Zig implementation of Common Access Token (CTA-5007).","archived":false,"fork":false,"pushed_at":"2025-05-19T08:35:33.000Z","size":27,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-29T05:54:30.398Z","etag":null,"topics":["access","cat","common","common-access-tokens","commonaccesstoken","cta","please-use-better-authentication-mechanisms","token","tokens","zig","zig-package"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jedisct1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-16T09:39:42.000Z","updated_at":"2025-05-19T08:35:36.000Z","dependencies_parsed_at":"2025-05-20T00:02:05.198Z","dependency_job_id":null,"html_url":"https://github.com/jedisct1/zig-common-access-token","commit_stats":null,"previous_names":["jedisct1/zig-common-access-token"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jedisct1/zig-common-access-token","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fzig-common-access-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fzig-common-access-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fzig-common-access-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fzig-common-access-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jedisct1","download_url":"https://codeload.github.com/jedisct1/zig-common-access-token/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fzig-common-access-token/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29995910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access","cat","common","common-access-tokens","commonaccesstoken","cta","please-use-better-authentication-mechanisms","token","tokens","zig","zig-package"],"created_at":"2025-07-05T21:02:22.119Z","updated_at":"2026-03-02T08:01:49.266Z","avatar_url":"https://github.com/jedisct1.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Common Access Token (CAT) for Zig\n\nA Zig implementation of the Common Access Token (CAT) specification with HMAC signatures.\n\n## What is CAT?\n\nCommon Access Token (CAT) is a token format designed for authorization and authentication in distributed systems, particularly for media and content delivery applications. It provides a secure, compact, and efficient way to represent claims and authorization information between parties.\n\nCAT is built on established standards:\n- Based on [CBOR Web Token (CWT)](https://tools.ietf.org/html/rfc8392) format\n- Uses [CBOR Object Signing and Encryption (COSE)](https://tools.ietf.org/html/rfc8152) for cryptographic operations\n- Provides a binary alternative to JWT with smaller token sizes and more efficient processing\n\n## Overview\n\nThis library provides a complete implementation for generating and validating Common Access Tokens (CAT) using HMAC signatures. It is designed to be interoperable with other implementations like [node-cat](https://github.com/Eyevinn/node-cat) and [common-access-token](https://github.com/fastly/rust-cat).\n\nKey benefits of using CAT tokens:\n- Compact: Binary format results in smaller token sizes compared to text-based formats\n- Efficient: CBOR encoding/decoding is faster and requires less processing power\n- Secure: Built on established cryptographic standards\n- Extensible: Supports custom claims and extensions\n\n## Features\n\n- Token Operations:\n  - Generate CAT tokens with HMAC signatures (HS256)\n  - Validate CAT tokens with comprehensive security checks\n  - Support for token expiration and time-based validation\n\n- Claims Support:\n  - Standard CWT claims (issuer, subject, audience, expiration, etc.)\n  - CAT-specific claims (version, renewal, usage, data, authorization)\n  - Custom claim extension capability\n\n- CBOR Implementation:\n  - High-performance CBOR encoding/decoding\n  - Support for all CBOR data types\n  - Support for indefinite-length arrays, maps, and strings\n  - Support for floating-point numbers\n  - Support for tagged values\n\n- Error Handling:\n  - Comprehensive error types\n  - Detailed error messages\n  - Error context information\n  - Error recovery mechanisms\n\n- Integration:\n  - Interoperability with other CAT implementations\n  - Easy integration with Zig applications\n  - Comprehensive documentation and examples\n\n## Installation\n\nAdd this library to your `build.zig.zon` file:\n\n```zig\n.dependencies = .{\n    .zig_cat = .{\n        .url = \"https://github.com/yourusername/zig-cat/archive/refs/tags/v0.1.0.tar.gz\",\n        .hash = \"...\",\n    },\n},\n```\n\nThen in your `build.zig`:\n\n```zig\nconst zig_cat = b.dependency(\"zig_cat\", .{\n    .target = target,\n    .optimize = optimize,\n});\nexe.addModule(\"cat\", zig_cat.module(\"cat\"));\n```\n\n## Usage\n\n### Token Generation\n\nThis example demonstrates how to create a CAT token with standard claims:\n\n```zig\nconst std = @import(\"std\");\nconst cat = @import(\"cat\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Create a key for token signing\n    const key_hex = \"403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388\";\n    const key = try cat.util.hexToBytes(allocator, key_hex);\n    defer allocator.free(key);\n\n    // Create a map of keys\n    var keys = std.StringHashMap([]const u8).init(allocator);\n    defer keys.deinit();\n    try keys.put(\"Symmetric256\", key);\n\n    // Create CAT options\n    const cat_options = cat.CatOptions{\n        .keys = keys,\n        .expect_cwt_tag = true,\n    };\n\n    // Create a CAT instance\n    var cat_instance = cat.Cat.init(allocator, cat_options);\n    defer cat_instance.deinit();\n\n    // Create claims\n    var claims = cat.Claims.init(allocator);\n    defer claims.deinit();\n\n    try claims.setIssuer(\"example\");\n    try claims.setSubject(\"user123\");\n    try claims.setAudience(\"service\");\n\n    const now = cat.util.currentTimeSecs();\n    try claims.setExpiration(now + 120); // 2 minutes from now\n    try claims.setIssuedAt(now);\n\n    // Generate token\n    const token = try cat_instance.generate(claims, .{\n        .validation_type = cat.CatValidationType.Mac,\n        .alg = \"HS256\",\n        .kid = \"Symmetric256\",\n        .generate_cwt_id = true,\n    });\n    defer allocator.free(token);\n\n    std.debug.print(\"Generated token: {s}\\n\", .{token});\n}\n```\n\n### Token Validation\n\n```zig\nconst std = @import(\"std\");\nconst cat = @import(\"cat\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // The token to validate (e.g., from a client request)\n    const token = \"2D3RhEOhAQWhBExTeW1tZXRyaWMyNTZYS6YHWCA1YmJjNDI2NWVmYTAxOGI4YjU4Y2I5OTQyY2IwODFmMQFnZXhhbXBsZQQaaQpK1gYaaQpKXgJndXNlcjEyMwNnc2VydmljZVggNRE3wudeG0Fd-vJMZiLpNRO6WU9lrtByioSvzuAEi7U\";\n\n    // Create a key for token validation\n    const key_hex = \"403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388\";\n    const key = try cat.util.hexToBytes(allocator, key_hex);\n    defer allocator.free(key);\n\n    // Create a map of keys\n    var keys = std.StringHashMap([]const u8).init(allocator);\n    defer keys.deinit();\n    try keys.put(\"Symmetric256\", key);\n\n    // Create CAT options\n    const cat_options = cat.CatOptions{\n        .keys = keys,\n        .expect_cwt_tag = true,\n    };\n\n    // Create a CAT instance\n    var cat_instance = cat.Cat.init(allocator, cat_options);\n    defer cat_instance.deinit();\n\n    // Validate the token\n    var claims = try cat_instance.validate(token, cat.CatValidationType.Mac, .{\n        .issuer = \"example\",\n        .audience = null,\n    });\n    defer claims.deinit();\n\n    std.debug.print(\"Token is valid!\\n\", .{});\n    if (claims.getIssuer()) |issuer| {\n        std.debug.print(\"Issuer: {s}\\n\", .{issuer});\n    }\n    if (claims.getSubject()) |subject| {\n        std.debug.print(\"Subject: {s}\\n\", .{subject});\n    }\n}\n```\n\n## Examples\n\nThe library includes several ready-to-use examples in the `examples/` directory:\n\n- generate.zig: Demonstrates basic token generation with standard claims\n- validate.zig: Shows how to validate tokens and extract claims\n- interop.zig: Tests interoperability with the NodeJS implementation (node-cat)\n- cat_claims.zig: Demonstrates using CAT-specific claims for advanced use cases\n- minimal.zig: Simple example showing basic base64 encoding utilities\n\nTo run an example:\n\n```bash\n# Generate a token\nzig build generate\n\n# Validate a token (replace \u003ctoken\u003e with an actual token)\nzig build validate -- \u003ctoken\u003e\n\n# Test interoperability with NodeJS implementation\nzig build interop [-- \u003ctoken\u003e]\n\n# Use CAT-specific claims\nzig build cat_claims\n\n# Run minimal example\nzig build minimal\n```\n\n## Security Considerations\n\nWhen using CAT tokens in your applications, keep these security best practices in mind:\n\n1. Key Management:\n   - Store signing keys securely\n   - Rotate keys periodically\n   - Use different keys for different environments\n\n2. Token Validation:\n   - Always validate tokens before trusting their contents\n   - Check expiration times\n   - Verify the issuer and audience claims\n\n3. Token Lifetime:\n   - Use short-lived tokens when possible\n   - For longer sessions, consider refresh token patterns\n\n4. Claims:\n   - Only include necessary information in tokens\n   - Be cautious with sensitive data in claims\n\n## Compatibility\n\nThis library is designed to be interoperable with other CAT implementations:\n\n- [node-cat](https://github.com/Eyevinn/node-cat): The NodeJS reference implementation\n- [common-access-token](https://github.com/fastly/rust-cat): The Rust implementation\n- Other implementations that follow the CAT specification\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedisct1%2Fzig-common-access-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjedisct1%2Fzig-common-access-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedisct1%2Fzig-common-access-token/lists"}