feat: add native/Java auth SDK, docs, CI, and examples

Made-with: Cursor
2026-06-09 10:00:30 +08:00 · 2026-04-06 17:42:09 +08:00
commit 3894315759
35 changed files with 4825 additions and 0 deletions
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>cn.craftlabs</groupId>
+        <artifactId>craftlabs-auth-parent</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>craftlabs-auth-core</artifactId>
+    <name>CraftLabs Auth — core API</name>
+    <packaging>jar</packaging>
+</project>
@@ -0,0 +1,37 @@
+package cn.craftlabs.auth;
+
+/**
+ * 授权能力的统一契约：初始化、激活、校验许可、查询特性与释放等生命周期方法。
+ *
+ * <p>实现类负责加载对应 native 或远端适配器；调用方应在不再使用时调用 {@link #close()} 释放底层资源。
+ *
+ * <p>版权所有 © 广州创飞人工智能技术有限公司
+ *
+ * @author huangping@craftlabs.cn
+ */
+public interface AuthProvider extends AutoCloseable {
+    /** 使用 JSON 配置初始化授权上下文；可重复调用，实现类应妥善处理句柄重置。 */
+    AuthResult initialize(String configJson);
+
+    /** 使用许可密钥激活（具体语义由底层供应商决定）。 */
+    AuthResult activate(String licenseKey);
+
+    /** 校验当前许可是否有效。 */
+    AuthResult checkLicense();
+
+    /** 返回当前许可详情；具体字段含义与失败时的表现以各 {@link AuthProvider} 实现为准。 */
+    LicenseInfo getLicenseInfo();
+
+    /** 查询指定特性是否开启。 */
+    boolean hasFeature(String featureName);
+
+    /** 释放/注销当前许可占用（与 {@link #close()} 侧重点不同，依供应商语义）。 */
+    AuthResult release();
+
+    /** 会话心跳，用于在线校验或租约续期等场景。 */
+    AuthResult heartbeat();
+
+    /** 释放 native 或远端资源；接口关闭后不得再调用其他方法。 */
+    @Override
+    void close();
+}
@@ -0,0 +1,50 @@
+package cn.craftlabs.auth;
+
+import java.util.Objects;
+
+/**
+ * 单次授权操作的结果：成功与否及 UTF-8 说明信息（可能来自 native，勿假定固定文案）。
+ *
+ * <p>版权所有 © 广州创飞人工智能技术有限公司
+ *
+ * @author huangping@craftlabs.cn
+ */
+public final class AuthResult {
+    private final boolean success;
+    private final String message;
+
+    public AuthResult(boolean success, String message) {
+        this.success = success;
+        this.message = message != null ? message : "";
+    }
+
+    public boolean isSuccess() {
+        return success;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        AuthResult that = (AuthResult) o;
+        return success == that.success && Objects.equals(message, that.message);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(success, message);
+    }
+
+    @Override
+    public String toString() {
+        return "AuthResult{success=" + success + ", message='" + message + '\'' + '}';
+    }
+}
@@ -0,0 +1,68 @@
+package cn.craftlabs.auth;
+
+import java.util.Collections;
+import java.util.Date;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * 当前许可快照：是否已授权、过期时间及特性开关映射（不可变视图）。
+ *
+ * <p>版权所有 © 广州创飞人工智能技术有限公司
+ *
+ * @author huangping@craftlabs.cn
+ */
+public final class LicenseInfo {
+    private final boolean licensed;
+    private final Date expirationDate;
+    private final Map<String, Boolean> features;
+
+    public LicenseInfo(boolean licensed, Date expirationDate, Map<String, Boolean> features) {
+        this.licensed = licensed;
+        this.expirationDate = expirationDate;
+        this.features =
+                features == null ? Collections.emptyMap() : Collections.unmodifiableMap(features);
+    }
+
+    public boolean isLicensed() {
+        return licensed;
+    }
+
+    public Date getExpirationDate() {
+        return expirationDate;
+    }
+
+    public Map<String, Boolean> getFeatures() {
+        return features;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        LicenseInfo that = (LicenseInfo) o;
+        return licensed == that.licensed
+                && Objects.equals(expirationDate, that.expirationDate)
+                && Objects.equals(features, that.features);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(licensed, expirationDate, features);
+    }
+
+    @Override
+    public String toString() {
+        return "LicenseInfo{licensed="
+                + licensed
+                + ", expirationDate="
+                + expirationDate
+                + ", features="
+                + features
+                + '}';
+    }
+}
@@ -0,0 +1,32 @@
+package cn.craftlabs.auth.internal;
+
+import cn.craftlabs.auth.AuthResult;
+import cn.craftlabs.auth.LicenseInfo;
+
+/**
+ * JNI 入口：与 {@code jni_bridge.cpp} 中的 {@code Java_cn_craftlabs_auth_internal_NativeBridge_*}
+ * 函数签名一一对应，由各 {@code AuthProvider} 实现所在的模块加载同名 native 库后使用。
+ *
+ * <p>版权所有 © 广州创飞人工智能技术有限公司
+ *
+ * @author huangping@craftlabs.cn
+ */
+public final class NativeBridge {
+    private NativeBridge() {}
+
+    public static native long nativeInitialize(String configJson);
+
+    public static native void nativeDestroy(long handle);
+
+    public static native AuthResult nativeActivate(long handle, String licenseKey);
+
+    public static native AuthResult nativeCheckLicense(long handle);
+
+    public static native LicenseInfo nativeGetLicenseInfo(long handle);
+
+    public static native boolean nativeHasFeature(long handle, String featureName);
+
+    public static native AuthResult nativeRelease(long handle);
+
+    public static native AuthResult nativeHeartbeat(long handle);
+}